diff options
| author | Igor Pashev <pashev.igor@gmail.com> | 2014-10-26 12:33:50 +0400 |
|---|---|---|
| committer | Igor Pashev <pashev.igor@gmail.com> | 2014-10-26 12:33:50 +0400 |
| commit | 47e6e7c84f008a53061e661f31ae96629bc694ef (patch) | |
| tree | 648a07f3b5b9d67ce19b0fd72e8caa1175c98f1a /man | |
| download | pcp-47e6e7c84f008a53061e661f31ae96629bc694ef.tar.gz | |
Debian 3.9.10debian/3.9.10debian
Diffstat (limited to 'man')
405 files changed, 64367 insertions, 0 deletions
diff --git a/man/Check b/man/Check new file mode 100755 index 0000000..3842f1f --- /dev/null +++ b/man/Check @@ -0,0 +1,71 @@ +#!/bin/sh +# +# Check various man pages for consistency issues related to +# possible changes in the code base +# + +tmp=/var/tmp/$$ +trap "rm -f $tmp.*; exit 0" 0 1 2 3 15 + +# man pages that are not in the GNUmakefile will not be included +# in the build +for dir in man? +do + cd $dir + for file in * + do + [ "$file" = GNUmakefile ] && continue + if grep "[ ]$file" GNUmakefile >/dev/null + then + : + else + echo "$dir/$file: not in GNUmakefile" + fi + done + cd .. +done + +# completeness of PM_ERR codes in man3/pcpintro.3 +# +if [ -x ../src/pmerr/pmerr ] +then + ../src/pmerr/pmerr -l +else + echo >&2 "Warning: using installed pmerr not newly built one ..." + pmerr -l +fi \ +| sed \ + -e 's/^-[0-9]*[ ]*//' \ + -e 's/[ ].*//' \ + -e '/^$/d' \ +| sort >$tmp.codes + +awk <man3/pcpintro.3 ' +/^.TP/ { want = 1; next } +want == 1 && /^.B PM_ERR/ { print $2 } + { want = 0 }' \ +| sort >$tmp.desc + +comm -23 $tmp.codes $tmp.desc >$tmp.tmp +if [ -s $tmp.tmp ] +then + echo "Error codes defined but not documented in man3/pcpintro.3:" + sed -e 's/^/ /' $tmp.tmp +fi +comm -13 $tmp.codes $tmp.desc >$tmp.tmp +if [ -s $tmp.tmp ] +then + echo "Error codes documented in man3/pcpintro.3 but not defined:" + sed -e 's/^/ /' $tmp.tmp +fi + +# references to Irix are probably needing to be retired ... other +# than the previously checked exceptions +# +grep -r -i irix man? \ +| sed \ + -e '/man5\/pmns.5:.*IRIX:[A-Z]/d' \ + -e '/man1\/pcpintro.1:.*MacOSX, IRIX, AIX/d' \ + -e '/man1\/pmie.1:.*\/SGI_Admin\/books\/PCP_IRIX\//d' \ + -e '/man5\/pmns.5:#define IRIX 1/d' + diff --git a/man/GNUmakefile b/man/GNUmakefile new file mode 100644 index 0000000..a8f92c6 --- /dev/null +++ b/man/GNUmakefile @@ -0,0 +1,31 @@ +# +# Copyright (c) 2000,2004 Silicon Graphics, Inc. All Rights Reserved. +# +# This program is free software; you can redistribute it and/or modify it +# under the terms of the GNU General Public License as published by the +# Free Software Foundation; either version 2 of the License, or (at your +# option) any later version. +# +# This program is distributed in the hope that it will be useful, but +# WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +# or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +# for more details. +# + +TOPDIR = .. +include $(TOPDIR)/src/include/builddefs +-include ./GNUlocaldefs + +SUBDIRS = man1 man3 man5 html + +default :: default_pcp + +default_pcp : $(SUBDIRS) + $(SUBDIRS_MAKERULE) + +install :: default_pcp install_pcp + +install_pcp : $(SUBDIRS) + $(SUBDIRS_MAKERULE) + +include $(BUILDRULES) diff --git a/man/html/GNUmakefile b/man/html/GNUmakefile new file mode 100644 index 0000000..4f1d0f2 --- /dev/null +++ b/man/html/GNUmakefile @@ -0,0 +1,36 @@ +# +# Copyright (c) 2000,2004 Silicon Graphics, Inc. All Rights Reserved. +# +# This program is free software; you can redistribute it and/or modify it +# under the terms of the GNU General Public License as published by the +# Free Software Foundation; either version 2 of the License, or (at your +# option) any later version. +# +# This program is distributed in the hope that it will be useful, but +# WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +# or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +# for more details. +# + +TOPDIR = ../.. +include $(TOPDIR)/src/include/builddefs + +CSSFILES = $(shell echo *.css) +HTMLFILES = $(shell echo *.html) +LSRCFILES = $(HTMLFILES) $(CSSFILES) + +SUBDIRS = images cpuperf diskmodel diskperf importdata pmie pmview + +default :: default_pcp + +default_pcp : $(SUBDIRS) + $(SUBDIRS_MAKERULE) + +install :: default_pcp install_pcp + +install_pcp : $(SUBDIRS) + $(INSTALL) -m 755 -d $(PCP_BOOKS_DIR)/html + $(INSTALL) -m 644 $(HTMLFILES) $(CSSFILES) $(PCP_BOOKS_DIR)/html + $(SUBDIRS_MAKERULE) + +include $(BUILDRULES) diff --git a/man/html/cclicense.html b/man/html/cclicense.html new file mode 100644 index 0000000..cba93b6 --- /dev/null +++ b/man/html/cclicense.html @@ -0,0 +1,288 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> +<HTML> +<HEAD> + <meta http-equiv="content-type" content="text/html; charset=utf-8"> + <meta http-equiv="content-style-type" content="text/css"> + <link href="pcpdoc.css" rel="stylesheet" type="text/css"> + <link href="images/pcp.ico" rel="icon" type="image/ico"> + <TITLE>PCP Manual</TITLE> +</HEAD> +<BODY LANG="en-AU" TEXT="#000060" DIR="LTR"> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 STYLE="page-break-before: always"> + <TR> <TD WIDTH=64 HEIGHT=64><A HREF="http://pcp.io/"><IMG SRC="images/pmcharticon.png" NAME="pmcharticon" ALIGN=TOP WIDTH=64 HEIGHT=64 BORDER=0></A></TD> + <TD WIDTH=1><P> </P></TD> + <TD WIDTH=500><P VALIGN=MIDDLE ALIGN=LEFT><A HREF="index.html"><FONT COLOR="#cc0000">Home</FONT></A> · <A HREF="lab.pmchart.html"><FONT COLOR="#cc0000">Charts</FONT></A> · <A HREF="timecontrol.html"><FONT COLOR="#cc0000">Time Control</FONT></A></P></TD> + </TR> +</TABLE> +<H1 ALIGN=CENTER STYLE="margin-top: 0.48cm; margin-bottom: 0.32cm"><FONT SIZE=7>Creative Commons License</FONT></H1> +</TABLE> +<P>A number of the icons used in pmchart were originally sourced from the <A HREF="http://tango.freedesktop.org/">Tango Desktop Project</A>. +<P>You may use, distribute and copy those icons under the terms of the Creative Commons License, version 2.5, which is displayed below. The remaining icons, which are completely original works created specifically for pmchart, are distributed under the terms of the GNU General Public License (<A HREF="gpl.html">GPL</A>). The Scalable Vector Graphics (SVG) file associated with each icon explicitly lists which license is appropriate for each icon. +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> Creative Commons Attribution-ShareAlike 2.5 License Agreement</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> CREATIVE COMMONS CORPORATION IS NOT A LAW FIRM AND DOES NOT</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> PROVIDE LEGAL SERVICES. DISTRIBUTION OF THIS LICENSE DOES NOT</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> CREATE AN ATTORNEY-CLIENT RELATIONSHIP. CREATIVE COMMONS PROVIDES</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> THIS INFORMATION ON AN "AS-IS" BASIS. CREATIVE COMMONS MAKES</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> NO WARRANTIES REGARDING THE INFORMATION PROVIDED, AND DISCLAIMS</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> LIABILITY FOR DAMAGES RESULTING FROM ITS USE.</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> License</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> THE WORK (AS DEFINED BELOW) IS PROVIDED UNDER THE TERMS OF THIS</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> CREATIVE COMMONS PUBLIC LICENSE ("CCPL" OR "LICENSE"). THE WORK IS</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> PROTECTED BY COPYRIGHT AND/OR OTHER APPLICABLE LAW. ANY USE OF THE</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> WORK OTHER THAN AS AUTHORIZED UNDER THIS LICENSE OR COPYRIGHT LAW</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> IS PROHIBITED.</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> BY EXERCISING ANY RIGHTS TO THE WORK PROVIDED HERE, YOU ACCEPT AND</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> AGREE TO BE BOUND BY THE TERMS OF THIS LICENSE. THE LICENSOR GRANTS</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> YOU THE RIGHTS CONTAINED HERE IN CONSIDERATION OF YOUR ACCEPTANCE</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> OF SUCH TERMS AND CONDITIONS.</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> 1. Definitions</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> 1. "Collective Work" means a work, such as a periodical issue,</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> anthology or encyclopedia, in which the Work in its entirety in</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> unmodified form, along with a number of other contributions,</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> constituting separate and independent works in themselves,</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> are assembled into a collective whole. A work that constitutes</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> a Collective Work will not be considered a Derivative Work (as</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> defined below) for the purposes of this License. 2. "Derivative</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> Work" means a work based upon the Work or upon the Work and other</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> pre-existing works, such as a translation, musical arrangement,</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> dramatization, fictionalization, motion picture version,</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> sound recording, art reproduction, abridgment, condensation,</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> or any other form in which the Work may be recast, transformed,</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> or adapted, except that a work that constitutes a Collective</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> Work will not be considered a Derivative Work for the purpose</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> of this License. For the avoidance of doubt, where the Work is</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> a musical composition or sound recording, the synchronization of</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> the Work in timed-relation with a moving image ("synching") will</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> be considered a Derivative Work for the purpose of this License.</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> 3. "Licensor" means the individual or entity that offers the</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> Work under the terms of this License. 4. "Original Author"</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> means the individual or entity who created the Work. 5. "Work"</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> means the copyrightable work of authorship offered under the</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> terms of this License. 6. "You" means an individual or entity</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> exercising rights under this License who has not previously</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> violated the terms of this License with respect to the Work,</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> or who has received express permission from the Licensor to</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> exercise rights under this License despite a previous violation.</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> 7. "License Elements" means the following high-level license</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> attributes as selected by Licensor and indicated in the title</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> of this License: Attribution, ShareAlike.</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> 2. Fair Use Rights. Nothing in this license is intended to reduce,</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> limit, or restrict any rights arising from fair use, first sale or</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> other limitations on the exclusive rights of the copyright owner</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> under copyright law or other applicable laws.</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> 3. License Grant. Subject to the terms and conditions of this</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> License, Licensor hereby grants You a worldwide, royalty-free,</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> non-exclusive, perpetual (for the duration of the applicable</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> copyright) license to exercise the rights in the Work as stated</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> below:</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> 1. to reproduce the Work, to incorporate the Work into one or</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> more Collective Works, and to reproduce the Work as incorporated</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> in the Collective Works; 2. to create and reproduce Derivative</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> Works; 3. to distribute copies or phonorecords of, display</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> publicly, perform publicly, and perform publicly by means of a</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> digital audio transmission the Work including as incorporated in</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> Collective Works; 4. to distribute copies or phonorecords of,</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> display publicly, perform publicly, and perform publicly by</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> means of a digital audio transmission Derivative Works. 5.</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> For the avoidance of doubt, where the work is a musical</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> composition:</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> 1. Performance Royalties Under Blanket Licenses. Licensor</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> waives the exclusive right to collect, whether individually</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> or via a performance rights society (e.g. ASCAP,</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> BMI, SESAC), royalties for the public performance or</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> public digital performance (e.g. webcast) of the Work.</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> 2. Mechanical Rights and Statutory Royalties. Licensor</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> waives the exclusive right to collect, whether individually</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> or via a music rights society or designated agent</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> (e.g. Harry Fox Agency), royalties for any phonorecord</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> You create from the Work ("cover version") and distribute,</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> subject to the compulsory license created by 17 USC Section</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> 115 of the US Copyright Act (or the equivalent in other</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> jurisdictions).</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> 6. Webcasting Rights and Statutory Royalties. For the avoidance</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> of doubt, where the Work is a sound recording, Licensor waives</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> the exclusive right to collect, whether individually or via</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> a performance-rights society (e.g. SoundExchange), royalties</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> for the public digital performance (e.g. webcast) of the Work,</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> subject to the compulsory license created by 17 USC Section 114 of</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> the US Copyright Act (or the equivalent in other jurisdictions).</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> The above rights may be exercised in all media and formats whether</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> now known or hereafter devised. The above rights include the right</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> to make such modifications as are technically necessary to exercise</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> the rights in other media and formats. All rights not expressly</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> granted by Licensor are hereby reserved.</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> 4. Restrictions.The license granted in Section 3 above is expressly</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> made subject to and limited by the following restrictions:</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> 1. You may distribute, publicly display, publicly perform, or</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> publicly digitally perform the Work only under the terms of this</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> License, and You must include a copy of, or the Uniform Resource</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> Identifier for, this License with every copy or phonorecord of</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> the Work You distribute, publicly display, publicly perform, or</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> publicly digitally perform. You may not offer or impose any terms</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> on the Work that alter or restrict the terms of this License or</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> the recipients' exercise of the rights granted hereunder. You may</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> not sublicense the Work. You must keep intact all notices that</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> refer to this License and to the disclaimer of warranties. You</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> may not distribute, publicly display, publicly perform, or</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> publicly digitally perform the Work with any technological</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> measures that control access or use of the Work in a manner</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> inconsistent with the terms of this License Agreement. The above</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> applies to the Work as incorporated in a Collective Work, but</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> this does not require the Collective Work apart from the Work</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> itself to be made subject to the terms of this License. If You</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> create a Collective Work, upon notice from any Licensor You must,</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> to the extent practicable, remove from the Collective Work any</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> credit as required by clause 4(c), as requested. If You create</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> a Derivative Work, upon notice from any Licensor You must,</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> to the extent practicable, remove from the Derivative Work any</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> credit as required by clause 4(c), as requested. 2. You may</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> distribute, publicly display, publicly perform, or publicly</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> digitally perform a Derivative Work only under the terms of</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> this License, a later version of this License with the same</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> License Elements as this License, or a Creative Commons iCommons</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> license that contains the same License Elements as this License</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> (e.g. Attribution-ShareAlike 2.5 Japan). You must include a copy</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> of, or the Uniform Resource Identifier for, this License or other</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> license specified in the previous sentence with every copy or</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> phonorecord of each Derivative Work You distribute, publicly</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> display, publicly perform, or publicly digitally perform. You</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> may not offer or impose any terms on the Derivative Works that</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> alter or restrict the terms of this License or the recipients'</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> exercise of the rights granted hereunder, and You must keep intact</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> all notices that refer to this License and to the disclaimer of</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> warranties. You may not distribute, publicly display, publicly</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> perform, or publicly digitally perform the Derivative Work</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> with any technological measures that control access or use</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> of the Work in a manner inconsistent with the terms of this</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> License Agreement. The above applies to the Derivative Work as</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> incorporated in a Collective Work, but this does not require</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> the Collective Work apart from the Derivative Work itself to be</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> made subject to the terms of this License. 3. If you distribute,</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> publicly display, publicly perform, or publicly digitally perform</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> the Work or any Derivative Works or Collective Works, You must</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> keep intact all copyright notices for the Work and provide,</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> reasonable to the medium or means You are utilizing: (i) the name</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> of the Original Author (or pseudonym, if applicable) if supplied,</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> and/or (ii) if the Original Author and/or Licensor designate</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> another party or parties (e.g. a sponsor institute, publishing</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> entity, journal) for attribution in Licensor's copyright notice,</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> terms of service or by other reasonable means, the name of such</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> party or parties; the title of the Work if supplied; to the extent</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> reasonably practicable, the Uniform Resource Identifier, if any,</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> that Licensor specifies to be associated with the Work, unless</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> such URI does not refer to the copyright notice or licensing</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> information for the Work; and in the case of a Derivative Work,</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> a credit identifying the use of the Work in the Derivative Work</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> (e.g., "French translation of the Work by Original Author," or</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> "Screenplay based on original Work by Original Author"). Such</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> credit may be implemented in any reasonable manner; provided,</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> however, that in the case of a Derivative Work or Collective Work,</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> at a minimum such credit will appear where any other comparable</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> authorship credit appears and in a manner at least as prominent</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> as such other comparable authorship credit.</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> 5. Representations, Warranties and Disclaimer</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> UNLESS OTHERWISE AGREED TO BY THE PARTIES IN WRITING, LICENSOR</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> OFFERS THE WORK AS-IS AND MAKES NO REPRESENTATIONS OR WARRANTIES</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> OF ANY KIND CONCERNING THE MATERIALS, EXPRESS, IMPLIED, STATUTORY</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> OR OTHERWISE, INCLUDING, WITHOUT LIMITATION, WARRANTIES OF TITLE,</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> MERCHANTIBILITY, FITNESS FOR A PARTICULAR PURPOSE, NONINFRINGEMENT,</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> OR THE ABSENCE OF LATENT OR OTHER DEFECTS, ACCURACY, OR THE PRESENCE</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> OF ABSENCE OF ERRORS, WHETHER OR NOT DISCOVERABLE. SOME JURISDICTIONS</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> DO NOT ALLOW THE EXCLUSION OF IMPLIED WARRANTIES, SO SUCH EXCLUSION</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> MAY NOT APPLY TO YOU.</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> 6. Limitation on Liability. EXCEPT TO THE EXTENT REQUIRED BY</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> APPLICABLE LAW, IN NO EVENT WILL LICENSOR BE LIABLE TO YOU ON ANY</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> LEGAL THEORY FOR ANY SPECIAL, INCIDENTAL, CONSEQUENTIAL, PUNITIVE OR</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> EXEMPLARY DAMAGES ARISING OUT OF THIS LICENSE OR THE USE OF THE WORK,</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> EVEN IF LICENSOR HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> 7. Termination</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> 1. This License and the rights granted hereunder will terminate</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> automatically upon any breach by You of the terms of this</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> License. Individuals or entities who have received Derivative</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> Works or Collective Works from You under this License,</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> however, will not have their licenses terminated provided</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> such individuals or entities remain in full compliance with</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> those licenses. Sections 1, 2, 5, 6, 7, and 8 will survive any</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> termination of this License. 2. Subject to the above terms</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> and conditions, the license granted here is perpetual (for the</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> duration of the applicable copyright in the Work). Notwithstanding</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> the above, Licensor reserves the right to release the Work under</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> different license terms or to stop distributing the Work at any</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> time; provided, however that any such election will not serve</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> to withdraw this License (or any other license that has been,</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> or is required to be, granted under the terms of this License),</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> and this License will continue in full force and effect unless</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> terminated as stated above.</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> 8. Miscellaneous</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> 1. Each time You distribute or publicly digitally perform the</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> Work or a Collective Work, the Licensor offers to the recipient</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> a license to the Work on the same terms and conditions as the</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> license granted to You under this License. 2. Each time You</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> distribute or publicly digitally perform a Derivative Work,</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> Licensor offers to the recipient a license to the original</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> Work on the same terms and conditions as the license granted</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> to You under this License. 3. If any provision of this License</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> is invalid or unenforceable under applicable law, it shall not</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> affect the validity or enforceability of the remainder of the</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> terms of this License, and without further action by the parties</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> to this agreement, such provision shall be reformed to the minimum</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> extent necessary to make such provision valid and enforceable.</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> 4. No term or provision of this License shall be deemed waived and</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> no breach consented to unless such waiver or consent shall be in</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> writing and signed by the party to be charged with such waiver</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> or consent. 5. This License constitutes the entire agreement</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> between the parties with respect to the Work licensed here. There</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> are no understandings, agreements or representations with respect</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> to the Work not specified here. Licensor shall not be bound by</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> any additional provisions that may appear in any communication</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> from You. This License may not be modified without the mutual</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> written agreement of the Licensor and You.</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> Creative Commons is not a party to this License, and makes no</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> warranty whatsoever in connection with the Work. Creative Commons</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> will not be liable to You or any party on any legal theory for</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> any damages whatsoever, including without limitation any general,</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> special, incidental or consequential damages arising in connection</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> to this license. Notwithstanding the foregoing two (2) sentences,</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> if Creative Commons has expressly identified itself as the Licensor</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> hereunder, it shall have all rights and obligations of Licensor.</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> Except for the limited purpose of indicating to the public that</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> the Work is licensed under the CCPL, neither party will use the</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> trademark "Creative Commons" or any related trademark or logo of</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> Creative Commons without the prior written consent of Creative</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> Commons. Any permitted use will be in compliance with Creative</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> Commons' then-current trademark usage guidelines, as may be published</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> on its website or otherwise made available upon request from time</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> to time.</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> Creative Commons may be contacted at http://creativecommons.org/.</pre> +<HR> +<CENTER> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0> + <TR> <TD WIDTH=50%><P>Copyright © 2007-2010 <A HREF="http://www.aconex.com/"><FONT COLOR="#000060">Aconex</FONT></A><BR>Copyright © 2000-2004 <A HREF="http://www.sgi.com/"><FONT COLOR="#000060">Silicon Graphics Inc</FONT></P></TD> + <TD WIDTH=50%><P ALIGN=RIGHT><A HREF="http://pcp.io/"><FONT COLOR="#000060">PCP Site</FONT></A><BR>Copyright © 2012-2014 <A HREF="http://www.redhat.com/"><FONT COLOR="#000060">Red Hat</FONT></P></TD> </TR> +</TABLE> +</CENTER> +</BODY> +</HTML> diff --git a/man/html/contacts.html b/man/html/contacts.html new file mode 100644 index 0000000..a53fed9 --- /dev/null +++ b/man/html/contacts.html @@ -0,0 +1,39 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> +<HTML> +<HEAD> + <meta http-equiv="content-type" content="text/html; charset=utf-8"> + <meta http-equiv="content-style-type" content="text/css"> + <link href="pcpdoc.css" rel="stylesheet" type="text/css"> + <link href="images/pcp.ico" rel="icon" type="image/ico"> + <TITLE>PCP Contacts</TITLE> +</HEAD> +<BODY LANG="en-AU" TEXT="#000060" DIR="LTR"> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 STYLE="page-break-before: always"> + <TR> <TD WIDTH=64 HEIGHT=64><A HREF="http://pcp.io/"><IMG SRC="images/pcpicon.png" NAME="pcpicon" ALIGN=TOP WIDTH=64 HEIGHT=64 BORDER=0></A></TD> + <TD WIDTH=1><P> </P></TD> + <TD WIDTH=500><P VALIGN=MIDDLE ALIGN=LEFT><A HREF="index.html"><FONT COLOR="#cc0000">Home</FONT></A> · <A HREF="lab.pmchart.html"><FONT COLOR="#cc0000">Charts</FONT></A> · <A HREF="timecontrol.html"><FONT COLOR="#cc0000">Time Control</FONT></A></P></TD> + </TR> +</TABLE> +<H1 ALIGN=CENTER STYLE="margin-top: 0.48cm; margin-bottom: 0.32cm"><FONT SIZE=7>Contacts</FONT></H1> +<BR><P><I>Mailing List</I> +<P> Questions and discussion about the toolkit should be directed to the PCP mailing list, <A HREF="http://pcp.io/mail.html">http://pcp.io/mail.html</A>. +<BR><P><I>IRC Channel</I> +<P> Several PCP developers and fellow users can be contacted via the <B>#pcp</B> channel on the OFTC network. +<BR><P><I>Web pages</I> +<P> The PCP web pages at <A HREF="http://pcp.io/">http://pcp.io/</A> cover PCP, PCP GUI and PCP Glider (the native Windows distribution of PCP). +<BR><P><I>Binaries</I> +<P> Pre-built packages for Redhat/SuSE, Debian/Ubuntu, Windows, MacOSX and Solaris can be downloaded from the PCP website at <A HREF="ftp://ftp.pcp.io/projects/pcp/download/">ftp://ftp.pcp.io/projects/pcp/download/</A>. +<BR><P><I>Source Code</I> +<P> GIT: git://git.pcp.io/pcp.git. +<P> GIT web: <A HREF="http://git.pcp.io/cgi-bin/gitweb.cgi?p=pcp.git">http://git.pcp.io/cgi-bin/gitweb.cgi?p=pcp.git</A>. +<P> Compressed source tarballs can be found alongside the binary packages above. +<P> +<HR> +<CENTER> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0> + <TR> <TD WIDTH=50%><P>Copyright © 2007-2010 <A HREF="http://www.aconex.com/"><FONT COLOR="#000060">Aconex</FONT></A><BR>Copyright © 2000-2004 <A HREF="http://www.sgi.com/"><FONT COLOR="#000060">Silicon Graphics Inc</FONT></P></TD> + <TD WIDTH=50%><P ALIGN=RIGHT><A HREF="http://pcp.io/"><FONT COLOR="#000060">PCP Site</FONT></A><BR>Copyright © 2012-2014 <A HREF="http://www.redhat.com/"><FONT COLOR="#000060">Red Hat</FONT></P></TD> </TR> +</TABLE> +</CENTER> +</BODY> +</HTML> diff --git a/man/html/cpuperf/GNUmakefile b/man/html/cpuperf/GNUmakefile new file mode 100644 index 0000000..76c7ab5 --- /dev/null +++ b/man/html/cpuperf/GNUmakefile @@ -0,0 +1,29 @@ +TOPDIR = ../../.. +include $(TOPDIR)/src/include/builddefs + +BUNDLE = cpuperf +BINTAR = $(BUNDLE).tar.gz +PCPLOGS = $(shell echo *.0 *.meta *.index) +CONFIGS = +LSRCFILES = $(PCPLOGS) $(CONFIGS) +LDIRT = $(BINTAR) manifest + +default: $(BINTAR) + +$(BINTAR): $(PCPLOGS) $(CONFIGS) + @ CDIR=`pwd`; cd ..; rm -f manifest; \ + for f in `echo $^`; do \ + echo $(BUNDLE)/$$f >> $$CDIR/manifest; \ + done; \ + $(TAR) -T $$CDIR/manifest -cf - | $(ZIP) --best > $$CDIR/$(BINTAR); \ + echo "Created $(BINTAR)" + +include $(BUILDRULES) + +install install-dev: default + $(INSTALL) -m 755 -d $(PCP_DEMOS_DIR)/tutorials + $(INSTALL) -m 644 $(BINTAR) $(PCP_DEMOS_DIR)/tutorials/$(BINTAR) + +default_pcp : default + +install_pcp : install diff --git a/man/html/cpuperf/babylon.percpu.0 b/man/html/cpuperf/babylon.percpu.0 Binary files differnew file mode 100644 index 0000000..6c5fddd --- /dev/null +++ b/man/html/cpuperf/babylon.percpu.0 diff --git a/man/html/cpuperf/babylon.percpu.index b/man/html/cpuperf/babylon.percpu.index Binary files differnew file mode 100644 index 0000000..938e63d --- /dev/null +++ b/man/html/cpuperf/babylon.percpu.index diff --git a/man/html/cpuperf/babylon.percpu.meta b/man/html/cpuperf/babylon.percpu.meta Binary files differnew file mode 100644 index 0000000..2eed638 --- /dev/null +++ b/man/html/cpuperf/babylon.percpu.meta diff --git a/man/html/cpuperf/moomba.pmkstat.0 b/man/html/cpuperf/moomba.pmkstat.0 Binary files differnew file mode 100644 index 0000000..e9ac65c --- /dev/null +++ b/man/html/cpuperf/moomba.pmkstat.0 diff --git a/man/html/cpuperf/moomba.pmkstat.index b/man/html/cpuperf/moomba.pmkstat.index Binary files differnew file mode 100644 index 0000000..5f165fd --- /dev/null +++ b/man/html/cpuperf/moomba.pmkstat.index diff --git a/man/html/cpuperf/moomba.pmkstat.meta b/man/html/cpuperf/moomba.pmkstat.meta Binary files differnew file mode 100644 index 0000000..457b35a --- /dev/null +++ b/man/html/cpuperf/moomba.pmkstat.meta diff --git a/man/html/credits.html b/man/html/credits.html new file mode 100644 index 0000000..f29780d --- /dev/null +++ b/man/html/credits.html @@ -0,0 +1,43 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> +<HTML> +<HEAD> + <meta http-equiv="content-type" content="text/html; charset=utf-8"> + <meta http-equiv="content-style-type" content="text/css"> + <link href="pcpdoc.css" rel="stylesheet" type="text/css"> + <link href="images/pcp.ico" rel="icon" type="image/ico"> + <TITLE>PCP Credits</TITLE> +</HEAD> +<BODY LANG="en-AU" TEXT="#000060" DIR="LTR"> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 STYLE="page-break-before: always"> + <TR> <TD WIDTH=64 HEIGHT=64><A HREF="http://pcp.io/"><IMG SRC="images/pcpicon.png" NAME="pcpicon" ALIGN=TOP WIDTH=64 HEIGHT=64 BORDER=0></A></TD> + <TD WIDTH=1><P> </P></TD> + <TD WIDTH=500><P VALIGN=MIDDLE ALIGN=LEFT><A HREF="index.html"><FONT COLOR="#cc0000">Home</FONT></A> · <A HREF="lab.pmchart.html"><FONT COLOR="#cc0000">Charts</FONT></A> · <A HREF="timecontrol.html"><FONT COLOR="#cc0000">Time Control</FONT></A></P></TD> + </TR> +</TABLE> +<H1 ALIGN=CENTER STYLE="margin-top: 0.48cm; margin-bottom: 0.32cm"><FONT SIZE=7>Credits</FONT></H1> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 BGCOLOR="#e2e2e2"> + <TR><TD WIDTH=100% BGCOLOR="#081c59"><P ALIGN=LEFT><FONT SIZE=5 COLOR="#ffffff"><B>PCP Development</B></FONT></P></TD></TR> +</TABLE> +<P>PCP originated on the SGI IRIX platform, with an initial team of developers of the early years working on the proprietary version of PCP. Thanks to these folk for the early years and what largely remains the core architecture of PCP.</P> +<P>Since PCP was open sourced, there have been many contributors from many individuals, organisations and companies (Aconex, Debian, IBM, Intel, Red Hat, SuSE, to name just a few).</P> + +<P>The pmchart graphical display also makes extensive use of the services offered by two excellent software libraries.<UL><LI><A HREF="http://www.trolltech.com/qt/">Qt</A>: Cross-Platform Rich Client Development Framework +<LI><A HREF="http://qwt.sourceforge.net/">QWT</A>: Qt Widgets for Technical Applications</UL> + +<P><BR></P> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 BGCOLOR="#e2e2e2"> + <TR><TD WIDTH=100% BGCOLOR="#081c59"><P ALIGN=LEFT><FONT SIZE=5 COLOR="#ffffff"><B>PCP Glider Development</B></FONT></P></TD></TR> +</TABLE> +<P>The PCP Glider project, the native PCP toolkit for Windows, exists thanks to the efforts of several individuals and groups.</P> +<P>The initial port of PCP to Windows used the Cygwin POSIX emulation layer. This was (several years) later abandoned for a number of practical reasons, and replaced with a version that builds on the efforts of the <A HREF="http://strawberryperl.com/">Strawberry Perl</A> and <A HREF="http://mingw.org/">MinGW</A> communities.</P> +<P>Many thanks to Curtis Jewell from the Strawberry Perl crew for his aid many times in helping with and improving this distribution which forms the base of PCP Glider.</P> +<P><BR></P> +<HR> +<CENTER> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0> + <TR> <TD WIDTH=50%><P>Copyright © 2007-2010 <A HREF="http://www.aconex.com/"><FONT COLOR="#000060">Aconex</FONT></A><BR>Copyright © 2000-2004 <A HREF="http://www.sgi.com/"><FONT COLOR="#000060">Silicon Graphics Inc</FONT></P></TD> + <TD WIDTH=50%><P ALIGN=RIGHT><A HREF="http://pcp.io/"><FONT COLOR="#000060">PCP Site</FONT></A><BR>Copyright © 2012-2014 <A HREF="http://www.redhat.com/"><FONT COLOR="#000060">Red Hat</FONT></P></TD> </TR> +</TABLE> +</CENTER> +</BODY> +</HTML> diff --git a/man/html/diskmodel/GNUmakefile b/man/html/diskmodel/GNUmakefile new file mode 100644 index 0000000..1378937 --- /dev/null +++ b/man/html/diskmodel/GNUmakefile @@ -0,0 +1,32 @@ +TOPDIR = ../../.. +include $(TOPDIR)/src/include/builddefs + +BUNDLE = diskmodel +BINTAR = $(BUNDLE).tar.gz +PCPLOGS = $(shell echo *.0 *.meta *.index) +CONFIGS = model.fio model.folio model.view +MODELS = model.pl model.xls nasread.out naswrite.out +LSRCFILES = $(PCPLOGS) $(CONFIGS) $(MODELS) +LDIRT = $(BINTAR) manifest + +default: $(BINTAR) + +$(BINTAR): $(PCPLOGS) $(CONFIGS) $(MODELS) + @ CDIR=`pwd`; cd ..; rm -f manifest; \ + for f in `echo $^`; do \ + echo $(BUNDLE)/$$f >> $$CDIR/manifest; \ + done; \ + $(TAR) -T $$CDIR/manifest -cf - | $(ZIP) --best > $$CDIR/$(BINTAR); \ + echo "Created $(BINTAR)" + +include $(BUILDRULES) + +install install-dev: default + $(INSTALL) -m 755 -d $(PCP_DEMOS_DIR)/tutorials + $(INSTALL) -m 644 $(BINTAR) $(PCP_DEMOS_DIR)/tutorials/$(BINTAR) + $(INSTALL) -m 755 -d $(PCP_BOOKS_DIR)/html/$(BUNDLE) + $(INSTALL) -m 644 $(MODELS) $(CONFIGS) $(PCP_BOOKS_DIR)/html/$(BUNDLE) + +default_pcp : default + +install_pcp : install diff --git a/man/html/diskmodel/dbdata.0 b/man/html/diskmodel/dbdata.0 Binary files differnew file mode 100644 index 0000000..a0bbce9 --- /dev/null +++ b/man/html/diskmodel/dbdata.0 diff --git a/man/html/diskmodel/dbdata.index b/man/html/diskmodel/dbdata.index Binary files differnew file mode 100644 index 0000000..7e72345 --- /dev/null +++ b/man/html/diskmodel/dbdata.index diff --git a/man/html/diskmodel/dbdata.meta b/man/html/diskmodel/dbdata.meta Binary files differnew file mode 100644 index 0000000..ce13ca7 --- /dev/null +++ b/man/html/diskmodel/dbdata.meta diff --git a/man/html/diskmodel/model.fio b/man/html/diskmodel/model.fio new file mode 100644 index 0000000..00a32b9 --- /dev/null +++ b/man/html/diskmodel/model.fio @@ -0,0 +1,96 @@ +# fio job file - modeling NAS/DB I/O patterns based on a number +# of PCP disk metrics (iops, throughput, queuelen) from our mel +# production storage on 2010/07/14. +# +# Basic usage: +# [ args="--latency-log --bandwidth-log" ] +# fio $args --output=nas_read_analysis.log --section=nas_read_load model.fio & +# fio $args --output=nas_write_analysis.log --section=nas_write_load model.fio & +# wait +# fio $args --output=db_log_analysis.log --section=db_log_analysis model.fio & +# fio $args --output=db_analysis.log --section=db_load model.fio & +# wait +# fio $args --output=bi_log_analysis.log --section=bi_log_analysis model.fio & +# fio $args --output=bi_analysis.log --section=bi_load model.fio & +# wait +# + +[global] +directory=/iscsi +size=2G +numjobs=4 +runtime=300 +time_based + +[nas_read_load] +description=NAS reads workload model +ioscheduler=deadline +readwrite=read +filesize=150M +rate=2521k +bssplit=4k/5:8k/5:30k/80:60k/5:64k/5 +ioengine=psync # make sure we do no seeks, NFS wont be +direct=1 +iodepth=4 +openfiles=4 # model using number of active nfsd threads +nrfiles=4 + +[nas_write_load] +description=NAS writes workload model +ioscheduler=deadline +readwrite=write +filesize=150M +rate=1233k +bssplit=4k/5:8k/5:30k/80:60k/5:64k/5 +fsync_on_close=1 # application doing per-file (rename+)fsync +ioengine=psync # make sure we do no seeks, NFS wont be +direct=1 +iodepth=4 +openfiles=4 # model using number of active nfsd threads +nrfiles=4 + +[db_load] +description=Database (interactive) workload model +ioscheduler=noop +overwrite=1 +readwrite=rw # mixed sequential reads and writes +rwmixread=64 # 64% read, 36% write ratio based on averages +direct=1 +iodepth=2 # based on average queuelen +filesize=150M +rate_iops=145,82 +bssplit=4k/5,4k/5:8k/90,8k/90:16k/5,16k/5 +ioengine=psync +iodepth=2 +openfiles=1 +nrfiles=1 + +[bi_load] +description=Database (business intelligence) workload model +ioscheduler=noop +overwrite=1 +readwrite=rw # mixed sequential reads and writes +rwmixread=93 # 93% read, 7% write ratio based on averages +direct=1 +filesize=150M +rate_iops=864,67 +bssplit=4k/4,4k/4:48k/90,8k/96:64k/5,:128k/1, +ioengine=psync +iodepth=8 +openfiles=1 +nrfiles=1 + +[log_load] +description=Database log writes (background) workload model +ioscheduler=noop +overwrite=1 +readwrite=write # only writes in this load +direct=1 +ioengine=psync +iodepth=4 +filesize=100M +bs=64k +thinktime=10000000 +thinktime_blocks=150 +nrfiles=1 +numjobs=1 diff --git a/man/html/diskmodel/model.folio b/man/html/diskmodel/model.folio new file mode 100644 index 0000000..6da60ab --- /dev/null +++ b/man/html/diskmodel/model.folio @@ -0,0 +1,10 @@ +PCPFolio +Version: 1 +# use pmafm(1) to process this PCP archive folio +# +Created: on verge at Wed Jul 28 12:36:42 EST 2010 +Creator: pmchart model.view +# Host Basename +# +Archive: db2 ./dbdata +Archive: nas2 ./nasdata diff --git a/man/html/diskmodel/model.pl b/man/html/diskmodel/model.pl new file mode 100644 index 0000000..58f2f20 --- /dev/null +++ b/man/html/diskmodel/model.pl @@ -0,0 +1,164 @@ +# +# Script generating a summary spreadsheet from production data +# +use strict; +use warnings; +use PCP::LogSummary; +use Spreadsheet::WriteExcel; + +my $workbook = Spreadsheet::WriteExcel->new('model.xls'); +my $naslog = "nasdata"; # PCP archive for NAS host +my $dblog = "dbdata"; # PCP archive for database host + +# Setup some spreadsheet metadata - fonts, colors, etc +# +my $heading = $workbook->add_format(); +$heading->set_bold(); +$heading->set_italic(); +my $subheading = $workbook->add_format(); +$subheading->set_italic(); +$subheading->set_bg_color('silver'); +my $centercolumn = $workbook->add_format(); +$centercolumn->set_align('center'); +my $centerboldcolumn = $workbook->add_format(); +$centerboldcolumn->set_align('center'); +$centerboldcolumn->set_bold(); + +# Create a worksheet, configure a few columns +# +my $sheet = $workbook->add_worksheet(); +$sheet->set_column('A:A', 28); # metric names column +$sheet->set_column('B:B', 6); # instances column +$sheet->set_column('C:C', 14); # column for raw values +$sheet->set_column('D:D', 12); # metrics units column +$sheet->set_column('E:E', 18); # average size column +$sheet->set_column('F:F', 14); # read/write ratio column + +sub iops_ratio +{ + my ( $reads, $writes ) = @_; + my $total = $writes + $reads; + $writes /= $total; + $writes *= 100; + $writes = int($writes + 0.5); + $reads /= $total; + $reads *= 100; + $reads = int($reads + 0.5); + return "$reads:$writes"; +} + +# Write data - starting at row 0 and column 0, moving across and down +# +my $row = 0; +$sheet->write($row, 0, 'NAS (NFS) Workload Modelling', $heading); +$row++; +$sheet->write($row, 0, 'Metrics', $subheading); +$sheet->write($row, 1, '', $subheading); +$sheet->write($row, 2, '', $subheading); +$sheet->write($row, 3, '', $subheading); +$sheet->write($row, 4, 'Average I/O Size', $subheading); +$sheet->write($row, 5, 'I/O Ratio', $subheading); + +my @nas = ('disk.dev.read', 'disk.dev.read_bytes', 'disk.dev.write', + 'disk.dev.write_bytes', 'disk.dev.avactive'); +my $nasIO = PCP::LogSummary->new($naslog, \@nas, '@11:00', '@12:00'); + +foreach my $m ( @nas ) { + my $device = 'sdi'; + my $metric = metric_instance($m, $device); + $row++; + $sheet->write($row, 0, $m); + $sheet->write($row, 1, "[$device]"); + $sheet->write($row, 2, $$nasIO{$metric}{'average'}, $centercolumn); + $sheet->write($row, 3, $$nasIO{$metric}{'units'}); + if ($m eq 'disk.dev.read') { + my $thruput = metric_instance('disk.dev.read_bytes', $device); + my $result = $$nasIO{$thruput}{'average'} / $$nasIO{$metric}{'average'}; + $sheet->write($row, 4, $result, $centerboldcolumn); + + my $writers = metric_instance('disk.dev.write', $device); + my $writes = $$nasIO{$writers}{'average'}; + my $reads = $$nasIO{$metric}{'average'}; + $sheet->write($row, 5, iops_ratio($reads, $writes), $centerboldcolumn); + } + if ($m eq 'disk.dev.write') { + my $thruput = metric_instance('disk.dev.write_bytes', $device); + my $result = $$nasIO{$thruput}{'average'} / $$nasIO{$metric}{'average'}; + $sheet->write($row, 4, $result, $centerboldcolumn); + } +} +$row += 2; + +$sheet->write($row, 0, 'DB (Interactive) Workload Modelling', $heading); +$row++; +$sheet->write($row, 0, 'Metrics', $subheading); +$sheet->write($row, 1, '', $subheading); +$sheet->write($row, 2, '', $subheading); +$sheet->write($row, 3, '', $subheading); +$sheet->write($row, 4, 'Average I/O Size', $subheading); +$sheet->write($row, 5, 'I/O Ratio', $subheading); + +my @db = ('disk.dev.read', 'disk.dev.read_bytes', 'disk.dev.write', + 'disk.dev.write_bytes', 'disk.dev.queue_len', 'disk.dev.idle'); +my $dbIO = PCP::LogSummary->new($dblog, \@db, '@11:10', '@11:55'); + +foreach my $m ( @db ) { + my $device = 'F:'; + my $metric = metric_instance($m, $device); + $row++; + $sheet->write($row, 0, $m); + $sheet->write($row, 1, "[$device]"); + $sheet->write($row, 2, $$dbIO{$metric}{'average'}, $centercolumn); + $sheet->write($row, 3, $$dbIO{$metric}{'units'}); + if ($m eq 'disk.dev.read') { + my $thruput = metric_instance('disk.dev.read_bytes', $device); + my $result = $$dbIO{$thruput}{'average'} / $$dbIO{$metric}{'average'}; + $sheet->write($row, 4, $result, $centerboldcolumn); + + my $writers = metric_instance('disk.dev.write', $device); + my $writes = $$dbIO{$writers}{'average'}; + my $reads = $$dbIO{$metric}{'average'}; + $sheet->write($row, 5, iops_ratio($reads, $writes), $centerboldcolumn); + } + if ($m eq 'disk.dev.write') { + my $thruput = metric_instance('disk.dev.write_bytes', $device); + my $result = $$dbIO{$thruput}{'average'} / $$dbIO{$metric}{'average'}; + $sheet->write($row, 4, $result, $centerboldcolumn); + } +} +$row += 2; + +$sheet->write($row, 0, 'DB (Business Intel) Workload Modelling', $heading); +$row++; +$sheet->write($row, 0, 'Metrics', $subheading); +$sheet->write($row, 1, '', $subheading); +$sheet->write($row, 2, '', $subheading); +$sheet->write($row, 3, '', $subheading); +$sheet->write($row, 4, 'Average I/O Size', $subheading); +$sheet->write($row, 5, 'I/O Ratio', $subheading); + +my $dbBI = PCP::LogSummary->new($dblog, \@db, '@11:00', '@11:05'); + +foreach my $m ( @db ) { + my $device = 'F:'; + my $metric = metric_instance($m, $device); + $row++; + $sheet->write($row, 0, $m); + $sheet->write($row, 1, "[$device]"); + $sheet->write($row, 2, $$dbBI{$metric}{'average'}, $centercolumn); + $sheet->write($row, 3, $$dbBI{$metric}{'units'}); + if ($m eq 'disk.dev.read') { + my $thruput = metric_instance('disk.dev.read_bytes', $device); + my $result = $$dbBI{$thruput}{'average'} / $$dbBI{$metric}{'average'}; + $sheet->write($row, 4, $result, $centerboldcolumn); + my $writers = metric_instance('disk.dev.write', $device); + my $writes = $$dbBI{$writers}{'average'}; + my $reads = $$dbBI{$metric}{'average'}; + $sheet->write($row, 5, iops_ratio($reads, $writes), $centerboldcolumn); + } + if ($m eq 'disk.dev.write') { + my $thruput = metric_instance('disk.dev.write_bytes', $device); + my $result = $$dbBI{$thruput}{'average'} / $$dbBI{$metric}{'average'}; + $sheet->write($row, 4, $result, $centerboldcolumn); + } +} diff --git a/man/html/diskmodel/model.view b/man/html/diskmodel/model.view new file mode 100644 index 0000000..f46e38e --- /dev/null +++ b/man/html/diskmodel/model.view @@ -0,0 +1,23 @@ +#kmchart +version 1 + +view "Database" + +chart title "Data Device IOPs [db2]" style stacking + plot legend "Reads" color yellow host db2 metric disk.dev.read instance F: + plot legend "Writes" color blue host db2 metric disk.dev.write instance F: + +chart title "Data Device Throughput [db2]" style stacking + plot legend "Read rate" color yellow host db2 metric disk.dev.read_bytes instance F: + plot legend "Write rate" color blue host db2 metric disk.dev.write_bytes instance F: + +view "Filestore" + +chart title "Filestore Device IOPs [nas2]" style stacking + plot legend "Reads" color yellow host nas2 metric disk.dev.read instance sdi + plot legend "Writes" color blue host nas2 metric disk.dev.write instance sdi + +chart title "Filestore Device Throughput [nas2]" style stacking + plot legend "Read rate" color yellow host nas2 metric disk.dev.read_bytes instance sdi + plot legend "Write rate" color blue host nas2 metric disk.dev.write_bytes instance sdi + diff --git a/man/html/diskmodel/model.xls b/man/html/diskmodel/model.xls Binary files differnew file mode 100644 index 0000000..83c4d80 --- /dev/null +++ b/man/html/diskmodel/model.xls diff --git a/man/html/diskmodel/nasdata.0 b/man/html/diskmodel/nasdata.0 Binary files differnew file mode 100644 index 0000000..56da9de --- /dev/null +++ b/man/html/diskmodel/nasdata.0 diff --git a/man/html/diskmodel/nasdata.index b/man/html/diskmodel/nasdata.index Binary files differnew file mode 100644 index 0000000..fcf001d --- /dev/null +++ b/man/html/diskmodel/nasdata.index diff --git a/man/html/diskmodel/nasdata.meta b/man/html/diskmodel/nasdata.meta Binary files differnew file mode 100644 index 0000000..cc6a0cd --- /dev/null +++ b/man/html/diskmodel/nasdata.meta diff --git a/man/html/diskmodel/nasread.out b/man/html/diskmodel/nasread.out new file mode 100644 index 0000000..37bec93 --- /dev/null +++ b/man/html/diskmodel/nasread.out @@ -0,0 +1,62 @@ +nas_read_load: (groupid=0, jobs=1): err= 0: pid=4109 + Description : [NAS reads workload model] + read : io=739MB, bw=2,523KB/s, iops=78, runt=300003msec + clat (usec): min=190, max=176K, avg=3343.45, stdev=2480.24 + lat (usec): min=191, max=176K, avg=3344.00, stdev=2480.24 + bw (KB/s) : min= 2301, max= 2808, per=25.02%, avg=2525.62, stdev=40.32 + cpu : usr=0.45%, sys=0.23%, ctx=45630, majf=0, minf=59 + IO depths : 1=100.0%, 2=0.0%, 4=0.0%, 8=0.0%, 16=0.0%, 32=0.0%, >=64=0.0% + submit : 0=0.0%, 4=100.0%, 8=0.0%, 16=0.0%, 32=0.0%, 64=0.0%, >=64=0.0% + complete : 0=0.0%, 4=100.0%, 8=0.0%, 16=0.0%, 32=0.0%, 64=0.0%, >=64=0.0% + issued r/w: total=23441/0, short=0/0 + lat (usec): 250=0.20%, 500=2.01%, 750=7.90%, 1000=7.59% + lat (msec): 2=9.44%, 4=35.22%, 10=36.87%, 20=0.56%, 50=0.20% + lat (msec): 250=0.01% +nas_read_load: (groupid=0, jobs=1): err= 0: pid=4110 + Description : [NAS reads workload model] + read : io=739MB, bw=2,523KB/s, iops=78, runt=300009msec + clat (usec): min=180, max=133K, avg=3369.74, stdev=2422.27 + lat (usec): min=180, max=133K, avg=3370.26, stdev=2422.26 + bw (KB/s) : min= 2125, max= 2984, per=25.02%, avg=2525.62, stdev=46.79 + cpu : usr=0.43%, sys=0.23%, ctx=45893, majf=0, minf=58 + IO depths : 1=100.0%, 2=0.0%, 4=0.0%, 8=0.0%, 16=0.0%, 32=0.0%, >=64=0.0% + submit : 0=0.0%, 4=100.0%, 8=0.0%, 16=0.0%, 32=0.0%, 64=0.0%, >=64=0.0% + complete : 0=0.0%, 4=100.0%, 8=0.0%, 16=0.0%, 32=0.0%, 64=0.0%, >=64=0.0% + issued r/w: total=23434/0, short=0/0 + lat (usec): 250=0.16%, 500=2.11%, 750=7.41%, 1000=7.53% + lat (msec): 2=9.76%, 4=34.88%, 10=37.32%, 20=0.61%, 50=0.21% + lat (msec): 100=0.01%, 250=0.01% +nas_read_load: (groupid=0, jobs=1): err= 0: pid=4111 + Description : [NAS reads workload model] + read : io=739MB, bw=2,524KB/s, iops=78, runt=300001msec + clat (usec): min=185, max=65,061, avg=3316.17, stdev=2339.06 + lat (usec): min=185, max=65,062, avg=3316.69, stdev=2339.06 + bw (KB/s) : min= 2335, max= 2765, per=25.02%, avg=2525.66, stdev=39.46 + cpu : usr=0.45%, sys=0.22%, ctx=45733, majf=0, minf=58 + IO depths : 1=100.0%, 2=0.0%, 4=0.0%, 8=0.0%, 16=0.0%, 32=0.0%, >=64=0.0% + submit : 0=0.0%, 4=100.0%, 8=0.0%, 16=0.0%, 32=0.0%, 64=0.0%, >=64=0.0% + complete : 0=0.0%, 4=100.0%, 8=0.0%, 16=0.0%, 32=0.0%, 64=0.0%, >=64=0.0% + issued r/w: total=23414/0, short=0/0 + lat (usec): 250=0.15%, 500=2.08%, 750=8.24%, 1000=8.01% + lat (msec): 2=10.06%, 4=34.33%, 10=36.27%, 20=0.61%, 50=0.23% + lat (msec): 100=0.01% +nas_read_load: (groupid=0, jobs=1): err= 0: pid=4112 + Description : [NAS reads workload model] + read : io=739MB, bw=2,523KB/s, iops=77, runt=300008msec + clat (usec): min=177, max=180K, avg=3341.21, stdev=2583.65 + lat (usec): min=177, max=180K, avg=3341.75, stdev=2583.65 + bw (KB/s) : min= 2330, max= 2730, per=25.02%, avg=2525.71, stdev=41.97 + cpu : usr=0.45%, sys=0.23%, ctx=45816, majf=0, minf=58 + IO depths : 1=100.0%, 2=0.0%, 4=0.0%, 8=0.0%, 16=0.0%, 32=0.0%, >=64=0.0% + submit : 0=0.0%, 4=100.0%, 8=0.0%, 16=0.0%, 32=0.0%, 64=0.0%, >=64=0.0% + complete : 0=0.0%, 4=100.0%, 8=0.0%, 16=0.0%, 32=0.0%, 64=0.0%, >=64=0.0% + issued r/w: total=23393/0, short=0/0 + lat (usec): 250=0.17%, 500=2.10%, 750=8.34%, 1000=7.81% + lat (msec): 2=9.65%, 4=34.22%, 10=36.91%, 20=0.56%, 50=0.23% + lat (msec): 100=0.01%, 250=0.01% + +Run status group 0 (all jobs): + READ: io=2,957MB, aggrb=10,094KB/s, minb=2,584KB/s, maxb=2,584KB/s, mint=300001msec, maxt=300009msec + +Disk stats (read/write): + sdh: ios=96851/85786, merge=580/357, ticks=315854/1940893, in_queue=2256741, util=73.11% diff --git a/man/html/diskmodel/naswrite.out b/man/html/diskmodel/naswrite.out new file mode 100644 index 0000000..b72b4c6 --- /dev/null +++ b/man/html/diskmodel/naswrite.out @@ -0,0 +1,62 @@ +nas_write_load: (groupid=0, jobs=1): err= 0: pid=4103 + Description : [NAS writes workload model] + write: io=361MB, bw=1,233KB/s, iops=37, runt=300026msec + clat (usec): min=276, max=1,325K, avg=2721.65, stdev=47070.32 + lat (usec): min=277, max=1,325K, avg=2722.20, stdev=47070.32 + bw (KB/s) : min= 34, max= 4486, per=25.12%, avg=1239.08, stdev=178.78 + cpu : usr=0.07%, sys=0.08%, ctx=22911, majf=0, minf=35 + IO depths : 1=100.0%, 2=0.0%, 4=0.0%, 8=0.0%, 16=0.0%, 32=0.0%, >=64=0.0% + submit : 0=0.0%, 4=100.0%, 8=0.0%, 16=0.0%, 32=0.0%, 64=0.0%, >=64=0.0% + complete : 0=0.0%, 4=100.0%, 8=0.0%, 16=0.0%, 32=0.0%, 64=0.0%, >=64=0.0% + issued r/w: total=0/11386, short=0/0 + lat (usec): 500=7.47%, 750=37.05%, 1000=38.94% + lat (msec): 2=15.25%, 4=0.40%, 10=0.40%, 20=0.23%, 50=0.02% + lat (msec): 100=0.07%, 250=0.02%, 500=0.01%, 1000=0.01%, 2000=0.13% +nas_write_load: (groupid=0, jobs=1): err= 0: pid=4104 + Description : [NAS writes workload model] + write: io=361MB, bw=1,233KB/s, iops=37, runt=300019msec + clat (usec): min=246, max=1,339K, avg=2744.08, stdev=47828.98 + lat (usec): min=247, max=1,339K, avg=2744.61, stdev=47828.99 + bw (KB/s) : min= 159, max= 4390, per=25.09%, avg=1237.54, stdev=145.93 + cpu : usr=0.08%, sys=0.09%, ctx=22978, majf=0, minf=36 + IO depths : 1=100.0%, 2=0.0%, 4=0.0%, 8=0.0%, 16=0.0%, 32=0.0%, >=64=0.0% + submit : 0=0.0%, 4=100.0%, 8=0.0%, 16=0.0%, 32=0.0%, 64=0.0%, >=64=0.0% + complete : 0=0.0%, 4=100.0%, 8=0.0%, 16=0.0%, 32=0.0%, 64=0.0%, >=64=0.0% + issued r/w: total=0/11375, short=0/0 + lat (usec): 250=0.01%, 500=6.45%, 750=36.13%, 1000=38.38% + lat (msec): 2=17.59%, 4=0.66%, 10=0.37%, 20=0.16%, 50=0.02% + lat (msec): 100=0.07%, 250=0.02%, 2000=0.14% +nas_write_load: (groupid=0, jobs=1): err= 0: pid=4105 + Description : [NAS writes workload model] + write: io=361MB, bw=1,233KB/s, iops=38, runt=300003msec + clat (usec): min=236, max=1,341K, avg=2719.56, stdev=46987.83 + lat (usec): min=236, max=1,341K, avg=2720.10, stdev=46987.83 + bw (KB/s) : min= 4, max= 4525, per=25.11%, avg=1238.19, stdev=173.06 + cpu : usr=0.08%, sys=0.08%, ctx=22919, majf=0, minf=36 + IO depths : 1=100.0%, 2=0.0%, 4=0.0%, 8=0.0%, 16=0.0%, 32=0.0%, >=64=0.0% + submit : 0=0.0%, 4=100.0%, 8=0.0%, 16=0.0%, 32=0.0%, 64=0.0%, >=64=0.0% + complete : 0=0.0%, 4=100.0%, 8=0.0%, 16=0.0%, 32=0.0%, 64=0.0%, >=64=0.0% + issued r/w: total=0/11429, short=0/0 + lat (usec): 250=0.02%, 500=7.89%, 750=37.06%, 1000=40.38% + lat (msec): 2=13.08%, 4=0.63%, 10=0.41%, 20=0.27%, 50=0.02% + lat (msec): 100=0.07%, 250=0.02%, 500=0.01%, 1000=0.01%, 2000=0.13% +nas_write_load: (groupid=0, jobs=1): err= 0: pid=4106 + Description : [NAS writes workload model] + write: io=361MB, bw=1,233KB/s, iops=38, runt=300013msec + clat (usec): min=244, max=1,326K, avg=2723.53, stdev=46927.49 + lat (usec): min=245, max=1,326K, avg=2724.08, stdev=46927.49 + bw (KB/s) : min= 177, max= 4412, per=25.09%, avg=1237.60, stdev=146.61 + cpu : usr=0.08%, sys=0.09%, ctx=22951, majf=0, minf=36 + IO depths : 1=100.0%, 2=0.0%, 4=0.0%, 8=0.0%, 16=0.0%, 32=0.0%, >=64=0.0% + submit : 0=0.0%, 4=100.0%, 8=0.0%, 16=0.0%, 32=0.0%, 64=0.0%, >=64=0.0% + complete : 0=0.0%, 4=100.0%, 8=0.0%, 16=0.0%, 32=0.0%, 64=0.0%, >=64=0.0% + issued r/w: total=0/11451, short=0/0 + lat (usec): 250=0.02%, 500=7.13%, 750=38.34%, 1000=37.93% + lat (msec): 2=15.12%, 4=0.61%, 10=0.38%, 20=0.21%, 50=0.02% + lat (msec): 100=0.07%, 250=0.04%, 2000=0.14% + +Run status group 0 (all jobs): + WRITE: io=1,445MB, aggrb=4,932KB/s, minb=1,262KB/s, maxb=1,262KB/s, mint=300003msec, maxt=300026msec + +Disk stats (read/write): + sdh: ios=88419/89190, merge=530/442, ticks=290558/2570922, in_queue=2861475, util=73.81% diff --git a/man/html/diskperf/GNUmakefile b/man/html/diskperf/GNUmakefile new file mode 100644 index 0000000..e30070d --- /dev/null +++ b/man/html/diskperf/GNUmakefile @@ -0,0 +1,29 @@ +TOPDIR = ../../.. +include $(TOPDIR)/src/include/builddefs + +BUNDLE = diskperf +BINTAR = $(BUNDLE).tar.gz +PCPLOGS = $(shell echo *.0 *.meta *.index) +CONFIGS = waitio.view +LSRCFILES = $(PCPLOGS) $(CONFIGS) +LDIRT = $(BINTAR) manifest + +default: $(BINTAR) + +$(BINTAR): $(PCPLOGS) $(CONFIGS) + @ CDIR=`pwd`; cd ..; rm -f manifest; \ + for f in `echo $^`; do \ + echo $(BUNDLE)/$$f >> $$CDIR/manifest; \ + done; \ + $(TAR) -T $$CDIR/manifest -cf - | $(ZIP) --best > $$CDIR/$(BINTAR); \ + echo "Created $(BINTAR)" + +include $(BUILDRULES) + +install install-dev: default + $(INSTALL) -m 755 -d $(PCP_DEMOS_DIR)/tutorials + $(INSTALL) -m 644 $(BINTAR) $(PCP_DEMOS_DIR)/tutorials/$(BINTAR) + +default_pcp : default + +install_pcp : install diff --git a/man/html/diskperf/waitio.0 b/man/html/diskperf/waitio.0 Binary files differnew file mode 100644 index 0000000..5c5cc7f --- /dev/null +++ b/man/html/diskperf/waitio.0 diff --git a/man/html/diskperf/waitio.index b/man/html/diskperf/waitio.index Binary files differnew file mode 100644 index 0000000..00c8f6f --- /dev/null +++ b/man/html/diskperf/waitio.index diff --git a/man/html/diskperf/waitio.meta b/man/html/diskperf/waitio.meta Binary files differnew file mode 100644 index 0000000..b577d23 --- /dev/null +++ b/man/html/diskperf/waitio.meta diff --git a/man/html/diskperf/waitio.view b/man/html/diskperf/waitio.view new file mode 100644 index 0000000..d06c1a9 --- /dev/null +++ b/man/html/diskperf/waitio.view @@ -0,0 +1,18 @@ +#pmchart +Version 2.0 host dynamic + +Global width 758 +Global height 470 +Global points 90 + +Chart Title "CPU Utilization" Style utilization + Plot Color #3f3f3f3fbfbf Host * Metric kernel.all.cpu.user + Plot Color #fefe00000000 Host * Metric kernel.all.cpu.sys + Plot Color #ffff3f3fbfbf Host * Metric kernel.all.cpu.sxbrk + Plot Color #e3e3e3e30000 Host * Metric kernel.all.cpu.intr + Plot Color #0000bfbfffff Host * Metric kernel.all.cpu.wait.total + Plot Color #0000ffff0000 Host * Metric kernel.all.cpu.idle +Chart Title "Disk Activity" Style stacking + Plot Color #-cycle Host * Metric disk.all.read + Plot Color #-cycle Host * Metric disk.all.write + diff --git a/man/html/glossary.html b/man/html/glossary.html new file mode 100644 index 0000000..7f015da --- /dev/null +++ b/man/html/glossary.html @@ -0,0 +1,48 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> +<HTML> +<HEAD> + <meta http-equiv="content-type" content="text/html; charset=utf-8"> + <meta http-equiv="content-style-type" content="text/css"> + <link href="pcpdoc.css" rel="stylesheet" type="text/css"> + <link href="images/pcp.ico" rel="icon" type="image/ico"> + <TITLE>PCP Glossary</TITLE> +</HEAD> +<BODY LANG="en-AU" TEXT="#000060" DIR="LTR"> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 STYLE="page-break-before: always"> + <TR> <TD WIDTH=64 HEIGHT=64><FONT COLOR="#000080"><A HREF="http://pcp.io/"><IMG SRC="images/pcpicon.png" NAME="pmcharticon" ALIGN=TOP WIDTH=64 HEIGHT=64 BORDER=0></A></FONT></TD> + <TD WIDTH=1><P> </P></TD> + <TD WIDTH=500><P VALIGN=MIDDLE ALIGN=LEFT><A HREF="index.html"><FONT COLOR="#cc0000">Home</FONT></A> · <A HREF="lab.pmchart.html"><FONT COLOR="#cc0000">Charts</FONT></A> · <A HREF="timecontrol.html"><FONT COLOR="#cc0000">Time Control</FONT></A></P></TD> + </TR> +</TABLE> +<H1 ALIGN=CENTER STYLE="margin-top: 0.48cm; margin-bottom: 0.32cm"><FONT SIZE=7>PCP Glossary</FONT></H1> + +<P><B>archive folio</B> - a collection of PCP <A HREF="#archive">archive logs</A> that can be processed as a group using <I>pmafm</I>.</P> +<P><B><A NAME="archive">archive log</B></A> - a set of physical files containing a collection of <A HREF="#metric">performance metrics</A> from a single <A HREF="#collector">collector system</A>. Archive logs are created by the program <I>pmlogger</I> and may be used with any PCP tools to provide retrospective performance +analysis.</P> +<P><B><A NAME="domain">domain</A> number</B> - each <A HREF="#PMDA">PMDA</A> is assigned a unique identifier (or domain number) that differentiates PMDAs on a collector system. For global consistency, a particular PMDA will be assigned the same domain number for <B>all</B> <A HREF="#collector">collector systems</A> on which it is installed.</P> +<P><B><A NAME="collector">collector system</B></A> - a host upon which a <A HREF="#PMCD">PMCD</A> is running to collect and export <A HREF="#metric">performance metrics</A> using the locally configured <A HREF="#PMDA">PMDAs</A>.</P> +<P><B><A NAME="instance identifiers">instance</B></A> <B>identifiers</B>- some <A HREF="#metric">performance metrics</A> have an associated <B>set</B> of values, e.g. the number of I/O disk operations is a metric, that has a set of values, one per disk spindle on any particular system. Each value is associated with an instance identifier that may be used to differentiate between the values that particular performance metric. Instance identifiers have both an internal (integer) encoding and an external (textual) name.</P> +<P><B>instance domain </B>- the set of <A HREF="#instance">instance identifiers</A> for a single <A HREF="#metric">performance metric</A>. Note that many metrics may share the same instance domain, e.g. per CPU, or per network interface, or per Web server, and the members of an instance domain are likely to be different on different hosts.</P> +<P><B><A NAME="monitor">monitor system</B></A> - a host upon which the PCP monitor tools are installed to support the display, plotting, visualization and automated reasoning, using <A HREF="#metric">performance metrics</A> fetched from a <A HREF="#PMDA">PMDA</A>, or from a PCP archive log.</P> +<P><B><A NAME="PCP">PCP</B></A> - the Performance Co-Pilot toolkit, a suite of tools useful for system level performance management.</P> +<P><B>PCP GUI</B> - utilities that build on the base PCP software providing additional <A HREF="#monitor">monitor</A> functionality, graphical user interface (GUI) tools in particular.</P> +<P><B>PCP Glider</B> - a distribution of software that provides PCP and PCP GUI, along with essential supporting tools and libraries for the Microsoft Windows platform.</P> +<P><B><A NAME="metric">performance metric</B></A> - any performance-related measurement of activity or resource utilization.</P> +<P><B>PDU</B> - Protocol Data Unit. In the PCP context this relates to the encoding of PCP requests into messages for transmission via TCP/IP. PDUs are used to implement all communication between the PCP monitor tools and a <A HREF="#PMCD">PMCD</A>, and between a PMCD and those <A HREF="#PMDA">PMDAs</A> that execute as separate processes.</P> +<P><B><A NAME="PMAPI">PMAPI</B></A> - Performance Metrics Application Programming Interface. The interface by which an application developer gains access to PCP services that relate to the fetching of <A HREF="#metric">performance metrics</A>.</P> +<P><B><A NAME="PMCD">PMCD</B></A> - Performance Metrics Collection Daemon. On each host configured as a PCP <A HREF="#collector">collector</A>, the PMCD services in-coming requests and controls the operation of the <A HREF="#PMDA">PMDAs</A>.</P> +<P><B><A NAME="PMDA">PMDA</B></A> - Performance Metrics Domain Agent. Each PMDA includes the methods necessary to instantiate <A HREF="#metric">performance metrics</A> from a particular subsystem, e.g. the kernel or a RDBMS or an application, and is launched by the <A HREF="#PMCD">PMCD</A>. It is expected that customized PMDAs will be developed for applications with critical performance impacts.</P> +<P><B>PMCS</B> - Performance Metrics Collection System. The infrastructure used to collect, export and transport <A HREF="#metric">performance metrics</A>, usually the combination of <A HREF="#PMCD">PMCD</A>, <A HREF="#PMDA">PMDAs</A> and <A HREF="#PMAPI">PMAPI</A> services.</P> +<P><B>PMNS</B> - Performance Metrics Name Space. A user-visible mapping between external names and PMIDs for <A HREF="#metric">performance metrics</A>. The PMNS is managed by <A HREF="#pmcd">PMCD</A> and its <A HREF="#PMDA">PMDAs</A>.</P> +<P><B>PMID</B> - Performance Metrics Identifier. Every <A HREF="#metric">performance metric</A> has an associated unique identifier. The high-order bits of the PMID encode the corresponding <A HREF="#PMDA">PMDA</A>'s <A HREF="#domain">domain</A> number.</P> + +<P><BR></P> +<HR> +<CENTER> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0> + <TR> <TD WIDTH=50%><P>Copyright © 2007-2010 <A HREF="http://www.aconex.com/"><FONT COLOR="#000060">Aconex</FONT></A><BR>Copyright © 2000-2004 <A HREF="http://www.sgi.com/"><FONT COLOR="#000060">Silicon Graphics Inc</FONT></P></TD> + <TD WIDTH=50%><P ALIGN=RIGHT><A HREF="http://pcp.io/"><FONT COLOR="#000060">PCP Site</FONT></A><BR>Copyright © 2012-2014 <A HREF="http://www.redhat.com/"><FONT COLOR="#000060">Red Hat</FONT></P></TD> </TR> +</TABLE> +</CENTER> +</BODY> +</HTML> diff --git a/man/html/gpl.html b/man/html/gpl.html new file mode 100644 index 0000000..c95a9a8 --- /dev/null +++ b/man/html/gpl.html @@ -0,0 +1,372 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> +<HTML> +<HEAD> + <meta http-equiv="content-type" content="text/html; charset=utf-8"> + <meta http-equiv="content-style-type" content="text/css"> + <link href="pcpdoc.css" rel="stylesheet" type="text/css"> + <link href="images/pcp.ico" rel="icon" type="image/ico"> + <TITLE>PCP Manual</TITLE> +</HEAD> +<BODY LANG="en-AU" TEXT="#000060" DIR="LTR"> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 STYLE="page-break-before: always"> + <TR> <TD WIDTH=64 HEIGHT=64><A HREF="http://pcp.io/"><IMG SRC="images/pcpicon.png" NAME="pcpicon" ALIGN=TOP WIDTH=64 HEIGHT=64 BORDER=0></A></TD> + <TD WIDTH=1><P> </P></TD> + <TD WIDTH=500><P VALIGN=MIDDLE ALIGN=LEFT><A HREF="index.html"><FONT COLOR="#cc0000">Home</FONT></A> · <A HREF="lab.pmchart.html"><FONT COLOR="#cc0000">Charts</FONT></A> · <A HREF="timecontrol.html"><FONT COLOR="#cc0000">Time Control</FONT></A></P></TD> + </TR> +</TABLE> +<H1 ALIGN=CENTER STYLE="margin-top: 0.48cm; margin-bottom: 0.32cm"><FONT SIZE=7>GNU General Public License (GPL)</FONT></H1> +<P>The PCP software is copyright SGI, and many portions are copyright by other companies and individuals, including IBM, Aconex, Evostor, Redhat and Ken McDonell, amongst others.</P> +<P>Several libraries in PCP are licensed under the GNU Lesser General Public License (LGPL).</P> +<P>The PCP GUI software is copyright Aconex, with portions copyright Ken McDonell.</P> +<P>The terms of the GNU General Public License version 2 follow.</P> + +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> GNU GENERAL PUBLIC LICENSE</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> Version 2, June 1991</pre> +<pre style="-qt-paragraph-type:empty; margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"></pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> Copyright (C) 1989, 1991 Free Software Foundation, Inc.</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> 51 Franklin Street, Fifth Floor, Boston, MA 02110, USA</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> Everyone is permitted to copy and distribute verbatim copies</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> of this license document, but changing it is not allowed.</pre> +<pre style="-qt-paragraph-type:empty; margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"></pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> Preamble</pre> +<pre style="-qt-paragraph-type:empty; margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"></pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> The licenses for most software are designed to take away your</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> freedom to share and change it. By contrast, the GNU General Public</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> License is intended to guarantee your freedom to share and change free</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> software--to make sure the software is free for all its users. This</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> General Public License applies to most of the Free Software</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> Foundation's software and to any other program whose authors commit to</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> using it. (Some other Free Software Foundation software is covered by</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> the GNU Library General Public License instead.) You can apply it to</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> your programs, too.</pre> +<pre style="-qt-paragraph-type:empty; margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"></pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> When we speak of free software, we are referring to freedom, not</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> price. Our General Public Licenses are designed to make sure that you</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> have the freedom to distribute copies of free software (and charge for</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> this service if you wish), that you receive source code or can get it</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> if you want it, that you can change the software or use pieces of it</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> in new free programs; and that you know you can do these things.</pre> +<pre style="-qt-paragraph-type:empty; margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"></pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> To protect your rights, we need to make restrictions that forbid</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> anyone to deny you these rights or to ask you to surrender the rights.</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> These restrictions translate to certain responsibilities for you if you</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> distribute copies of the software, or if you modify it.</pre> +<pre style="-qt-paragraph-type:empty; margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"></pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> For example, if you distribute copies of such a program, whether</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> gratis or for a fee, you must give the recipients all the rights that</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> you have. You must make sure that they, too, receive or can get the</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> source code. And you must show them these terms so they know their</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> rights.</pre> +<pre style="-qt-paragraph-type:empty; margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"></pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> We protect your rights with two steps: (1) copyright the software, and</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> (2) offer you this license which gives you legal permission to copy,</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> distribute and/or modify the software.</pre> +<pre style="-qt-paragraph-type:empty; margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"></pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> Also, for each author's protection and ours, we want to make certain</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> that everyone understands that there is no warranty for this free</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> software. If the software is modified by someone else and passed on, we</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> want its recipients to know that what they have is not the original, so</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> that any problems introduced by others will not reflect on the original</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> authors' reputations.</pre> +<pre style="-qt-paragraph-type:empty; margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"></pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> Finally, any free program is threatened constantly by software</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> patents. We wish to avoid the danger that redistributors of a free</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> program will individually obtain patent licenses, in effect making the</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> program proprietary. To prevent this, we have made it clear that any</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> patent must be licensed for everyone's free use or not licensed at all.</pre> +<pre style="-qt-paragraph-type:empty; margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"></pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> The precise terms and conditions for copying, distribution and</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> modification follow.</pre> +<pre style="-qt-paragraph-type:empty; margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"></pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> GNU GENERAL PUBLIC LICENSE</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION</pre> +<pre style="-qt-paragraph-type:empty; margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"></pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> 0. This License applies to any program or other work which contains</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> a notice placed by the copyright holder saying it may be distributed</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> under the terms of this General Public License. The "Program", below,</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> refers to any such program or work, and a "work based on the Program"</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> means either the Program or any derivative work under copyright law:</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> that is to say, a work containing the Program or a portion of it,</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> either verbatim or with modifications and/or translated into another</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> language. (Hereinafter, translation is included without limitation in</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> the term "modification".) Each licensee is addressed as "you".</pre> +<pre style="-qt-paragraph-type:empty; margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"></pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> Activities other than copying, distribution and modification are not</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> covered by this License; they are outside its scope. The act of</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> running the Program is not restricted, and the output from the Program</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> is covered only if its contents constitute a work based on the</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> Program (independent of having been made by running the Program).</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> Whether that is true depends on what the Program does.</pre> +<pre style="-qt-paragraph-type:empty; margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"></pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> 1. You may copy and distribute verbatim copies of the Program's</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> source code as you receive it, in any medium, provided that you</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> conspicuously and appropriately publish on each copy an appropriate</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> copyright notice and disclaimer of warranty; keep intact all the</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> notices that refer to this License and to the absence of any warranty;</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> and give any other recipients of the Program a copy of this License</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> along with the Program.</pre> +<pre style="-qt-paragraph-type:empty; margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"></pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> You may charge a fee for the physical act of transferring a copy, and</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> you may at your option offer warranty protection in exchange for a fee.</pre> +<pre style="-qt-paragraph-type:empty; margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"></pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> 2. You may modify your copy or copies of the Program or any portion</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> of it, thus forming a work based on the Program, and copy and</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> distribute such modifications or work under the terms of Section 1</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> above, provided that you also meet all of these conditions:</pre> +<pre style="-qt-paragraph-type:empty; margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"></pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> a) You must cause the modified files to carry prominent notices</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> stating that you changed the files and the date of any change.</pre> +<pre style="-qt-paragraph-type:empty; margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"></pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> b) You must cause any work that you distribute or publish, that in</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> whole or in part contains or is derived from the Program or any</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> part thereof, to be licensed as a whole at no charge to all third</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> parties under the terms of this License.</pre> +<pre style="-qt-paragraph-type:empty; margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"></pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> c) If the modified program normally reads commands interactively</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> when run, you must cause it, when started running for such</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> interactive use in the most ordinary way, to print or display an</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> announcement including an appropriate copyright notice and a</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> notice that there is no warranty (or else, saying that you provide</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> a warranty) and that users may redistribute the program under</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> these conditions, and telling the user how to view a copy of this</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> License. (Exception: if the Program itself is interactive but</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> does not normally print such an announcement, your work based on</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> the Program is not required to print an announcement.)</pre> +<pre style="-qt-paragraph-type:empty; margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"></pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> These requirements apply to the modified work as a whole. If</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> identifiable sections of that work are not derived from the Program,</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> and can be reasonably considered independent and separate works in</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> themselves, then this License, and its terms, do not apply to those</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> sections when you distribute them as separate works. But when you</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> distribute the same sections as part of a whole which is a work based</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> on the Program, the distribution of the whole must be on the terms of</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> this License, whose permissions for other licensees extend to the</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> entire whole, and thus to each and every part regardless of who wrote it.</pre> +<pre style="-qt-paragraph-type:empty; margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"></pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> Thus, it is not the intent of this section to claim rights or contest</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> your rights to work written entirely by you; rather, the intent is to</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> exercise the right to control the distribution of derivative or</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> collective works based on the Program.</pre> +<pre style="-qt-paragraph-type:empty; margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"></pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> In addition, mere aggregation of another work not based on the Program</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> with the Program (or with a work based on the Program) on a volume of</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> a storage or distribution medium does not bring the other work under</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> the scope of this License.</pre> +<pre style="-qt-paragraph-type:empty; margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"></pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> 3. You may copy and distribute the Program (or a work based on it,</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> under Section 2) in object code or executable form under the terms of</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> Sections 1 and 2 above provided that you also do one of the following:</pre> +<pre style="-qt-paragraph-type:empty; margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"></pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> a) Accompany it with the complete corresponding machine-readable</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> source code, which must be distributed under the terms of Sections</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> 1 and 2 above on a medium customarily used for software interchange; or,</pre> +<pre style="-qt-paragraph-type:empty; margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"></pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> b) Accompany it with a written offer, valid for at least three</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> years, to give any third party, for a charge no more than your</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> cost of physically performing source distribution, a complete</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> machine-readable copy of the corresponding source code, to be</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> distributed under the terms of Sections 1 and 2 above on a medium</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> customarily used for software interchange; or,</pre> +<pre style="-qt-paragraph-type:empty; margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"></pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> c) Accompany it with the information you received as to the offer</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> to distribute corresponding source code. (This alternative is</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> allowed only for noncommercial distribution and only if you</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> received the program in object code or executable form with such</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> an offer, in accord with Subsection b above.)</pre> +<pre style="-qt-paragraph-type:empty; margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"></pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> The source code for a work means the preferred form of the work for</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> making modifications to it. For an executable work, complete source</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> code means all the source code for all modules it contains, plus any</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> associated interface definition files, plus the scripts used to</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> control compilation and installation of the executable. However, as a</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> special exception, the source code distributed need not include</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> anything that is normally distributed (in either source or binary</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> form) with the major components (compiler, kernel, and so on) of the</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> operating system on which the executable runs, unless that component</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> itself accompanies the executable.</pre> +<pre style="-qt-paragraph-type:empty; margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"></pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> If distribution of executable or object code is made by offering</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> access to copy from a designated place, then offering equivalent</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> access to copy the source code from the same place counts as</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> distribution of the source code, even though third parties are not</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> compelled to copy the source along with the object code.</pre> +<pre style="-qt-paragraph-type:empty; margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"></pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> 4. You may not copy, modify, sublicense, or distribute the Program</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> except as expressly provided under this License. Any attempt</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> otherwise to copy, modify, sublicense or distribute the Program is</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> void, and will automatically terminate your rights under this License.</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> However, parties who have received copies, or rights, from you under</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> this License will not have their licenses terminated so long as such</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> parties remain in full compliance.</pre> +<pre style="-qt-paragraph-type:empty; margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"></pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> 5. You are not required to accept this License, since you have not</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> signed it. However, nothing else grants you permission to modify or</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> distribute the Program or its derivative works. These actions are</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> prohibited by law if you do not accept this License. Therefore, by</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> modifying or distributing the Program (or any work based on the</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> Program), you indicate your acceptance of this License to do so, and</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> all its terms and conditions for copying, distributing or modifying</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> the Program or works based on it.</pre> +<pre style="-qt-paragraph-type:empty; margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"></pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> 6. Each time you redistribute the Program (or any work based on the</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> Program), the recipient automatically receives a license from the</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> original licensor to copy, distribute or modify the Program subject to</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> these terms and conditions. You may not impose any further</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> restrictions on the recipients' exercise of the rights granted herein.</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> You are not responsible for enforcing compliance by third parties to</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> this License.</pre> +<pre style="-qt-paragraph-type:empty; margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"></pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> 7. If, as a consequence of a court judgment or allegation of patent</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> infringement or for any other reason (not limited to patent issues),</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> conditions are imposed on you (whether by court order, agreement or</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> otherwise) that contradict the conditions of this License, they do not</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> excuse you from the conditions of this License. If you cannot</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> distribute so as to satisfy simultaneously your obligations under this</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> License and any other pertinent obligations, then as a consequence you</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> may not distribute the Program at all. For example, if a patent</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> license would not permit royalty-free redistribution of the Program by</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> all those who receive copies directly or indirectly through you, then</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> the only way you could satisfy both it and this License would be to</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> refrain entirely from distribution of the Program.</pre> +<pre style="-qt-paragraph-type:empty; margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"></pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> If any portion of this section is held invalid or unenforceable under</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> any particular circumstance, the balance of the section is intended to</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> apply and the section as a whole is intended to apply in other</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> circumstances.</pre> +<pre style="-qt-paragraph-type:empty; margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"></pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> It is not the purpose of this section to induce you to infringe any</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> patents or other property right claims or to contest validity of any</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> such claims; this section has the sole purpose of protecting the</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> integrity of the free software distribution system, which is</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> implemented by public license practices. Many people have made</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> generous contributions to the wide range of software distributed</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> through that system in reliance on consistent application of that</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> system; it is up to the author/donor to decide if he or she is willing</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> to distribute software through any other system and a licensee cannot</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> impose that choice.</pre> +<pre style="-qt-paragraph-type:empty; margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"></pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> This section is intended to make thoroughly clear what is believed to</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> be a consequence of the rest of this License.</pre> +<pre style="-qt-paragraph-type:empty; margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"></pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> 8. If the distribution and/or use of the Program is restricted in</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> certain countries either by patents or by copyrighted interfaces, the</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> original copyright holder who places the Program under this License</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> may add an explicit geographical distribution limitation excluding</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> those countries, so that distribution is permitted only in or among</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> countries not thus excluded. In such case, this License incorporates</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> the limitation as if written in the body of this License.</pre> +<pre style="-qt-paragraph-type:empty; margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"></pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> 9. The Free Software Foundation may publish revised and/or new versions</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> of the General Public License from time to time. Such new versions will</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> be similar in spirit to the present version, but may differ in detail to</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> address new problems or concerns.</pre> +<pre style="-qt-paragraph-type:empty; margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"></pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> Each version is given a distinguishing version number. If the Program</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> specifies a version number of this License which applies to it and "any</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> later version", you have the option of following the terms and conditions</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> either of that version or of any later version published by the Free</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> Software Foundation. If the Program does not specify a version number of</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> this License, you may choose any version ever published by the Free Software</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> Foundation.</pre> +<pre style="-qt-paragraph-type:empty; margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"></pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> 10. If you wish to incorporate parts of the Program into other free</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> programs whose distribution conditions are different, write to the author</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> to ask for permission. For software which is copyrighted by the Free</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> Software Foundation, write to the Free Software Foundation; we sometimes</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> make exceptions for this. Our decision will be guided by the two goals</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> of preserving the free status of all derivatives of our free software and</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> of promoting the sharing and reuse of software generally.</pre> +<pre style="-qt-paragraph-type:empty; margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"></pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> NO WARRANTY</pre> +<pre style="-qt-paragraph-type:empty; margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"></pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> REPAIR OR CORRECTION.</pre> +<pre style="-qt-paragraph-type:empty; margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"></pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> POSSIBILITY OF SUCH DAMAGES.</pre> +<pre style="-qt-paragraph-type:empty; margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"></pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> END OF TERMS AND CONDITIONS</pre> +<pre style="-qt-paragraph-type:empty; margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"></pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> Appendix: How to Apply These Terms to Your New Programs</pre> +<pre style="-qt-paragraph-type:empty; margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"></pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> If you develop a new program, and you want it to be of the greatest</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> possible use to the public, the best way to achieve this is to make it</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> free software which everyone can redistribute and change under these terms.</pre> +<pre style="-qt-paragraph-type:empty; margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"></pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> To do so, attach the following notices to the program. It is safest</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> to attach them to the start of each source file to most effectively</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> convey the exclusion of warranty; and each file should have at least</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> the "copyright" line and a pointer to where the full notice is found.</pre> +<pre style="-qt-paragraph-type:empty; margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"></pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> <one line to give the program's name and a brief idea of what it does.></pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> Copyright (C) 19yy <name of author></pre> +<pre style="-qt-paragraph-type:empty; margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"></pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> This program is free software; you can redistribute it and/or modify</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> it under the terms of the GNU General Public License as published by</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> the Free Software Foundation; either version 2 of the License, or</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> (at your option) any later version.</pre> +<pre style="-qt-paragraph-type:empty; margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"></pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> This program is distributed in the hope that it will be useful,</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> but WITHOUT ANY WARRANTY; without even the implied warranty of</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> GNU General Public License for more details.</pre> +<pre style="-qt-paragraph-type:empty; margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"></pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> You should have received a copy of the GNU General Public License</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> along with this program; if not, write to the Free Software</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA</pre> +<pre style="-qt-paragraph-type:empty; margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"></pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> Also add information on how to contact you by electronic and paper mail.</pre> +<pre style="-qt-paragraph-type:empty; margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"></pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> If the program is interactive, make it output a short notice like this</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> when it starts in an interactive mode:</pre> +<pre style="-qt-paragraph-type:empty; margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"></pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> Gnomovision version 69, Copyright (C) 19yy name of author</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> This is free software, and you are welcome to redistribute it</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> under certain conditions; type `show c' for details.</pre> +<pre style="-qt-paragraph-type:empty; margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"></pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> The hypothetical commands `show w' and `show c' should show the appropriate</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> parts of the General Public License. Of course, the commands you use may</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> be called something other than `show w' and `show c'; they could even be</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> mouse-clicks or menu items--whatever suits your program.</pre> +<pre style="-qt-paragraph-type:empty; margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"></pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> You should also get your employer (if you work as a programmer) or your</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> school, if any, to sign a "copyright disclaimer" for the program, if</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> necessary. Here is a sample; alter the names:</pre> +<pre style="-qt-paragraph-type:empty; margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"></pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> Yoyodyne, Inc., hereby disclaims all copyright interest in the program</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> `Gnomovision' (which makes passes at compilers) written by James Hacker.</pre> +<pre style="-qt-paragraph-type:empty; margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"></pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> <signature of Ty Coon>, 1 April 1989</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> Ty Coon, President of Vice</pre> +<pre style="-qt-paragraph-type:empty; margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"></pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> This General Public License does not permit incorporating your program into</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> proprietary programs. If your program is a subroutine library, you may</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> consider it more useful to permit linking proprietary applications with the</pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> library. If this is what you want to do, use the GNU Library General</pre> +<pre style=" margin-top:0px; margin-bottom:12px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> Public License instead of this License.</pre> + +<P><BR></P> +<HR> +<CENTER> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0> + <TR> <TD WIDTH=50%><P>Copyright © 2007-2010 <A HREF="http://www.aconex.com/"><FONT COLOR="#000060">Aconex</FONT></A><BR>Copyright © 2000-2004 <A HREF="http://www.sgi.com/"><FONT COLOR="#000060">Silicon Graphics Inc</FONT></P></TD> + <TD WIDTH=50%><P ALIGN=RIGHT><A HREF="http://pcp.io/"><FONT COLOR="#000060">PCP Site</FONT></A><BR>Copyright © 2012-2014 <A HREF="http://www.redhat.com/"><FONT COLOR="#000060">Red Hat</FONT></P></TD> </TR> +</TABLE> +</CENTER> +</BODY> +</HTML> diff --git a/man/html/guide.redhat.html b/man/html/guide.redhat.html new file mode 100644 index 0000000..70420eb --- /dev/null +++ b/man/html/guide.redhat.html @@ -0,0 +1,522 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> +<HTML> +<HEAD> + <meta http-equiv="content-type" content="text/html; charset=utf-8"> + <meta http-equiv="content-style-type" content="text/css"> + <link href="pcpdoc.css" rel="stylesheet" type="text/css"> + <link href="images/pcp.ico" rel="icon" type="image/ico"> + <TITLE>Red Hat Quick Reference Guide</TITLE> +</HEAD> +<BODY LANG="en-AU" TEXT="#000060" DIR="LTR"> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 STYLE="page-break-before: always"> + <TR> <TD WIDTH=64 HEIGHT=64><FONT COLOR="#000080"><A HREF="http://pcp.io/"><IMG SRC="images/pcpicon.png" NAME="pcpicon" ALIGN=TOP WIDTH=64 HEIGHT=64 BORDER=0></A></FONT></TD> + <TD WIDTH=1><P> </P></TD> + <TD WIDTH=500><P VALIGN=MIDDLE ALIGN=LEFT><A HREF="index.html"><FONT COLOR="#cc0000">Home</FONT></A> · <A HREF="lab.pmchart.html"><FONT COLOR="#cc0000">Charts</FONT></A> · <A HREF="timecontrol.html"><FONT COLOR="#cc0000">Time Control</FONT></A></P></TD> + </TR> +</TABLE> +<H1 ALIGN=CENTER STYLE="margin-top: 0.48cm; margin-bottom: 0.32cm"><FONT SIZE=7>Red Hat Quick Reference Guide</FONT></H1> +<UL> + <LI><A HREF="#intro">Introduction</A> + <LI><A HREF="#install">Installation</A> + <UL> + <LI><A HREF="#collectors">Installing Collector Hosts</A> + <LI><A HREF="#monitors">Installing Monitor Hosts</A> + <LI><A HREF="#discovery">Dynamic Host Discovery</A> + <LI><A HREF="#healthcheck">Installation Health Check</A> + </UL> + <LI><A HREF="#systemlevel">System Level Performance Monitoring</A> + <UL> + <LI><A HREF="#live">Monitoring Live Performance Metrics</A> + <LI><A HREF="#retro">Retrospective Performance Analysis</A> + <LI><A HREF="#visual">Visualizing iostat and sar Data</A> + </UL> + <LI><A HREF="#processes">Process Level Performance Monitoring</A> + <UL> + <LI><A HREF="#processmon">Live and Retrospective Process Monitoring</A> + <LI><A HREF="#instrument">Application Instrumentation</A> + </UL> + <LI><A HREF="#pmie">Performance Metrics Inference</A> + <LI><A HREF="#web">Web Services</A> + <UL> + <LI><A HREF="#pmwebd">Performance Metrics Web Daemon</A> + <LI><A HREF="#browse">Web Interface for Performance Metrics</A> + </UL> + <LI><A HREF="#custom">Customizing and Extending PCP</A> + <LI><A HREF="#next">Additional Information</A> +</UL> + +<a name="intro"></a> +<H1>Introduction</H1> + +<P><A HREF="http://www.pcp.io/>Performance Co-Pilot</A> (PCP) is an open source framework and toolkit for monitoring, analyzing, and responding to details of live and historical system performance. PCP has a fully distributed, plug-in based architecture making it particularly well suited to centralized analysis of complex environments and systems. Custom performance metrics can be added using the C, C++, Perl, and Python interfaces. + +<P>This page provides quick instructions how to install and use PCP on a set of RHEL hosts of which one (a monitor host) will be used for monitoring and analyzing itself and other hosts (collector hosts). + +<a name="install"></a> +<H1>Installation</H1> + +<P>PCP is supported on RHEL 6.6+ and RHEL 7+ and is available from the <A HREF="http://fedoraproject.org/wiki/EPEL">EPEL</A> repositories for earlier versions. + +<P>For older releases, either enable EPEL with Yum (see <A HREF="http://fedoraproject.org/wiki/EPEL/FAQ#How_can_I_install_the_packages_from_the_EPEL_software_repository.3F">this page</A> for details - but be careful not to overwrite any RHEL packages with EPEL packages) or you can grab the latest PCP packages manually from the <A HREF="http://dl.fedoraproject.org/pub/epel/">EPEL repositories</A>. + +<a name="collectors"></a> +<H3>Installing Collector Hosts</H3> + +<TABLE WIDTH=100% BORDER=0 CELLPADDING=10 CELLSPACING=20> + <TR><TD BGCOLOR="#e2e2e2" WIDTH=70%><BR><IMG SRC="images/stepfwd_on.png" WIDTH=16 HEIGHT=16 BORDER=0> To install basic PCP tools and services and enable collecting performance data, simply run:<br><B> +<br> # yum install pcp +<br> # chkconfig pmcd on +<br> # service pmcd start +<br> # chkconfig pmlogger on +<br> # service pmlogger start +</B></TD></TR> +</TABLE> + +<P>This will enable the Performance Metrics Collector Daemon (pmcd) on the host which then in turn will control and request metrics on behalf of clients from various Performance Metrics Domain Agents (PMDAs). The PMDAs provide the actual data from different components (domains) in the system, for example from the Linux Kernel PMDA or the NFS Client PMDA. The default configuration includes over 1000 metrics with negligible overall overhead. Local PCP archive logs will also be enabled on the host for convenience with pmlogger (<A HREF="https://access.redhat.com/articles/1146283">RHKB 1146283</A> contains some additional logging related considerations). + +<TABLE WIDTH=100% BORDER=0 CELLPADDING=10 CELLSPACING=20> + <TR><TD BGCOLOR="#e2e2e2" WIDTH=70%><BR><IMG SRC="images/stepfwd_on.png" WIDTH=16 HEIGHT=16 BORDER=0> To enable PMDAs which are not enabled by default, for example the NFS Client PMDA, run the corresponding Install script:<br><B> +<br> # cd /var/lib/pcp/pmdas/nfsclient +<BR> # ./Install +</B></TD></TR> +</TABLE> + +<P>The client tools will contact local or remote PMCDs as needed, communication with PMCD over the network uses TCP port 44321 by default. + + +<a name="monitors"></a> +<H3>Installing Monitor Host</H3> + +<P>The following additional packages can be optionally installed on the monitoring host to extend the set of monitoring tools from the base pcp package. + +<TABLE WIDTH=100% BORDER=0 CELLPADDING=10 CELLSPACING=20> + <TR><TD BGCOLOR="#e2e2e2" WIDTH=70%><BR><IMG SRC="images/stepfwd_on.png" WIDTH=16 HEIGHT=16 BORDER=0> Install graphical analysis tools and documentation:<BR><B> +<BR># yum install pcp-doc pcp-gui +</B></TD></TR> +</TABLE> + +<P>To enable centralized archive log collection on the monitoring host, its pmlogger is configured to fetch performance metrics from collector hosts. Add each collector host to the pmlogger configuration file /etc/pcp/pmlogger/control and then restart the pmlogger service on the monitoring host. + +<TABLE WIDTH=100% BORDER=0 CELLPADDING=10 CELLSPACING=20> + <TR><TD BGCOLOR="#e2e2e2" WIDTH=70%><BR><IMG SRC="images/stepfwd_on.png" WIDTH=16 HEIGHT=16 BORDER=0> Enable recording of metrics from remote host <B><FONT COLOR="#cc0000">acme.com</FONT></B>:<B><BR> +<BR> # echo <FONT COLOR="#cc0000">acme.com</FONT> n n PCP_LOG_DIR/pmlogger/<FONT COLOR="#cc0000">acme.com</FONT> -r -T24h10m -c config.<FONT COLOR="#cc0000">acme.com</FONT> >> /etc/pcp/pmlogger/control +<BR> +<BR> # service pmlogger restart +</B></TD></TR> +</TABLE> + +<P>Checks for remote log collection will be done every half an hour. You may also wish to run /usr/libexec/pcp/bin/pmlogger_check -V -C manually (the service restart above issues this command internally). + +<P>Note that a default configuration file (config.acme.com above) will be generated if it does not exist already. This process is optional (a custom configuration for each host can be provided instead), see the pmlogconf manual page for details on this. + +<a name="discovery"></a> +<H3>Dynamic Host Discovery</H3> + +<P>In dynamic environments manually configuring every host is not feasible, perhaps even impossible. PCP Manager (PMMGR, from the pcp-manager RPM package) can be used instead of directly invoking PMLOGGER and PMIE to auto-discover and auto-configure new collector hosts. + +<TABLE WIDTH=100% BORDER=0 CELLPADDING=10 CELLSPACING=20> + <TR><TD BGCOLOR="#e2e2e2" WIDTH=70%><BR><IMG SRC="images/stepfwd_on.png" WIDTH=16 HEIGHT=16 BORDER=0> To install the PMMGR daemon and begin monitoring either statically or dynamically configured hosts, run:<br><B> +<br> # yum install pcp-manager +<br> # echo <FONT COLOR="#cc0000">acme.com</FONT> >> /etc/pcp/pmmgr/target-host +<br> # echo avahi >> /etc/pcp/pmmgr/target-discover +<br> # echo probe=<FONT COLOR="#cc0000">ip.addr.tup.le/netmask</FONT> >> /etc/pcp/pmmgr/target-discover +<br> # chkconfig pmmgr on +<br> # service pmmgr start +<br> # find /var/log/pcp/pmmgr +</B></TD></TR> +</TABLE> + +<TABLE WIDTH=100% BORDER=0 CELLPADDING=10 CELLSPACING=20> + <TR><TD BGCOLOR="#e2e2e2" WIDTH=70%><BR><IMG SRC="images/stepfwd_on.png" WIDTH=16 HEIGHT=16 BORDER=0> +Discover use of the PCP pmcd service on the local network:<BR><B> +<BR> $ pmfind -s pmcd</B> +</TD></TR> +</TABLE> + +<a name="healthcheck"></a> +<H3>Installation Health Check</H3> + +<P>Basic installation health check for running services, network connectivity between hosts, and enabled PMDAs can be done simply as follows. + +<TABLE WIDTH=100% BORDER=0 CELLPADDING=10 CELLSPACING=20> + <TR><TD BGCOLOR="#e2e2e2" WIDTH=70%><BR><IMG SRC="images/stepfwd_on.png" WIDTH=16 HEIGHT=16 BORDER=0> Check PCP services on remote host <B><FONT COLOR="#cc0000">munch</FONT></B> and historically, from a local archive for host <B><FONT COLOR="#cc0000">smash</FONT></B>:<BR><B> +<BR> $ pcp -h <FONT COLOR="#cc0000">munch</FONT></B><PRE> +Performance Co-Pilot configuration on munch: + platform: SunOS munch 5.11 oi_151a8 i86pc + hardware: 4 cpus, 3 disks, 4087MB RAM + timezone: EST-10 + pmcd: Version 3.8.9-1, 3 agents + pmda: pmcd mmv solaris +</PRE> +<B> +<BR> $ pcp -a /var/log/pcp/pmlogger/<FONT COLOR="#cc0000">smash</FONT>/20140729</B><PRE> +Performance Co-Pilot configuration on smash: + archive: /var/log/pcp/pmlogger/smash/20140729 + platform: Linux smash 2.6.32-279.46.1.el6.x86_64 #1 SMP Mon May 19 16:16:00 EDT 2014 x86_64 + hardware: 8 cpus, 2 disks, 1 node, 23960MB RAM + timezone: EST-10 + services: pmcd pmwebd + pmcd: Version 3.9.8-1, 13 agents + pmda: pmcd proc trace xfs sample sampledso linux mmv nvidia jbd2 + rpm dmcache simple + pmlogger: primary logger: smash/20140729.00.10 +</PRE></TD></TR> +</TABLE> + +<a name="systemlevel"></a> +<H1>System Level Performance Monitoring</H1> + +<P>PCP comes with a wide range of command line utilities for accessing live performance metrics via PMCDs or historical data using archive logs. The following examples illustrate some of the most useful use cases, please see the corresponding manual pages for each command for additional information. In the below examples -h <host> is always optional, the default is the local host. + +<a name="live"></a> +<H3>Monitoring Live Performance Metrics</H3> + +<TABLE WIDTH=100% BORDER=0 CELLPADDING=10 CELLSPACING=20> + <TR><TD BGCOLOR="#e2e2e2" WIDTH=70%><BR><IMG SRC="images/stepfwd_on.png" WIDTH=16 HEIGHT=16 BORDER=0> +Display all the enabled performance metrics on a host (use with -t to include a short description for each):<BR><B> +<BR> $ pminfo -h <FONT COLOR="#cc0000">acme.com</FONT></B> +</TD></TR> +</TABLE> + +<TABLE WIDTH=100% BORDER=0 CELLPADDING=10 CELLSPACING=20> + <TR><TD BGCOLOR="#e2e2e2" WIDTH=70%><BR><IMG SRC="images/stepfwd_on.png" WIDTH=16 HEIGHT=16 BORDER=0> +Display detailed information about a performance metric and its current values:<BR><B> +<BR> $ pminfo -dfmtT disk.partitions.read -h <FONT COLOR="#cc0000">acme.com</FONT></B> +</TD></TR> +</TABLE> + +<TABLE WIDTH=100% BORDER=0 CELLPADDING=10 CELLSPACING=20> + <TR><TD BGCOLOR="#e2e2e2" WIDTH=70%><BR><IMG SRC="images/stepfwd_on.png" WIDTH=16 HEIGHT=16 BORDER=0> +Monitor live disk write operations per partition with two second interval using fixed point notation (use -i instance to list only certain metrics and -r for raw values):<BR><B> +<BR> $ pmval -t 2sec -f 3 disk.partitions.write -h <FONT COLOR="#cc0000">acme.com</FONT></B> +</TD></TR> +</TABLE> + +<TABLE WIDTH=100% BORDER=0 CELLPADDING=10 CELLSPACING=20> + <TR><TD BGCOLOR="#e2e2e2" WIDTH=70%><BR><IMG SRC="images/stepfwd_on.png" WIDTH=16 HEIGHT=16 BORDER=0> +Monitor live CPU load, memory usage, and disk write operations per partition with two second interval using fixed width columns:<BR><B> +<BR> $ pmdumptext -i -l 'kernel.all.load[1]' mem.util.used disk.partitions.write -h <FONT COLOR="#cc0000">acme.com</FONT></B> +</TD></TR> +</TABLE> + +<TABLE WIDTH=100% BORDER=0 CELLPADDING=10 CELLSPACING=20> + <TR><TD BGCOLOR="#e2e2e2" WIDTH=70%><BR><IMG SRC="images/stepfwd_on.png" WIDTH=16 HEIGHT=16 BORDER=0> +Monitor system metrics in a top like window (this needs a large terminal):<BR><B> +<BR> $ pmatop -h <FONT COLOR="#cc0000">acme.com</FONT></B> +</TD></TR> +</TABLE> + +<TABLE WIDTH=100% BORDER=0 CELLPADDING=10 CELLSPACING=20> + <TR><TD BGCOLOR="#e2e2e2" WIDTH=70%><BR><IMG SRC="images/stepfwd_on.png" WIDTH=16 HEIGHT=16 BORDER=0> +Monitor system metrics in a sar like fashion with two second interval from two different hosts:<BR><B> +<BR> $ pmstat -t 2sec -h <FONT COLOR="#cc0000">acme1.com</FONT> -h <FONT COLOR="#cc0000">acme2.com</FONT></B> +</TD></TR> +</TABLE> + +<TABLE WIDTH=100% BORDER=0 CELLPADDING=10 CELLSPACING=20> + <TR><TD BGCOLOR="#e2e2e2" WIDTH=70%><BR><IMG SRC="images/stepfwd_on.png" WIDTH=16 HEIGHT=16 BORDER=0> +Monitor system metrics in an iostat like fashion with two second interval:<BR><B> +<BR> $ pmiostat -t 2sec -h <FONT COLOR="#cc0000">acme.com</FONT></B> +</TD></TR> +</TABLE> + +<TABLE WIDTH=100% BORDER=0 CELLPADDING=10 CELLSPACING=20> + <TR><TD BGCOLOR="#e2e2e2" WIDTH=70%><BR><IMG SRC="images/stepfwd_on.png" WIDTH=16 HEIGHT=16 BORDER=0> +Monitor performance metrics with a GUI application with two second default interval from two different hosts. Use File->New Chart to select metrics to be included in a new view and use File->Open View to use a predefined view:<BR><B> +<BR> $ pmchart -t 2sec -h <FONT COLOR="#cc0000">acme1.com</FONT> -h <FONT COLOR="#cc0000">acme2.com</FONT></B> +</TD></TR> +</TABLE> + +<a name="retro"></a> +<H3>Retrospective Performance Analysis</H3> + +<P>PCP archive logs are located under /var/log/pcp/pmlogger/<B><FONT COLOR="#cc0000">hostname</FONT></B>, and the archive names indicate the date they cover. Archives are self-contained, and machine-independent so can be transfered to any machine for offline analysis. + +<TABLE WIDTH=100% BORDER=0 CELLPADDING=10 CELLSPACING=20> + <TR><TD BGCOLOR="#e2e2e2" WIDTH=70%><BR><IMG SRC="images/stepfwd_on.png" WIDTH=16 HEIGHT=16 BORDER=0> +Check the host and the time period an archive covers:<BR><B> +<BR> $ pmdumplog -l <FONT COLOR="#cc0000">acme.com</FONT>/20140902</B> +</TD></TR> +</TABLE> + +<TABLE WIDTH=100% BORDER=0 CELLPADDING=10 CELLSPACING=20> + <TR><TD BGCOLOR="#e2e2e2" WIDTH=70%><BR><IMG SRC="images/stepfwd_on.png" WIDTH=16 HEIGHT=16 BORDER=0> +Check PCP configuration at the time when an archive was created:<BR><B> +<BR> $ pcp -a <FONT COLOR="#cc0000">acme.com</FONT>/20140902</B> +</TD></TR> +</TABLE> + +<TABLE WIDTH=100% BORDER=0 CELLPADDING=10 CELLSPACING=20> + <TR><TD BGCOLOR="#e2e2e2" WIDTH=70%><BR><IMG SRC="images/stepfwd_on.png" WIDTH=16 HEIGHT=16 BORDER=0> +Display all enabled performance metrics at the time when an archive was created:<BR><B> +<BR> $ pminfo -a <FONT COLOR="#cc0000">acme.com</FONT>/20140902</B> +</TD></TR> +</TABLE> + +<TABLE WIDTH=100% BORDER=0 CELLPADDING=10 CELLSPACING=20> + <TR><TD BGCOLOR="#e2e2e2" WIDTH=70%><BR><IMG SRC="images/stepfwd_on.png" WIDTH=16 HEIGHT=16 BORDER=0> +Display detailed information about a performance metric at the time when an archive was created:<BR><B> +<BR> $ pminfo -df mem.freemem -a <FONT COLOR="#cc0000">acme.com</FONT>/20140902</B> +</TD></TR> +</TABLE> + +<TABLE WIDTH=100% BORDER=0 CELLPADDING=10 CELLSPACING=20> + <TR><TD BGCOLOR="#e2e2e2" WIDTH=70%><BR><IMG SRC="images/stepfwd_on.png" WIDTH=16 HEIGHT=16 BORDER=0> +Dump past disk write operations per partition in an archive using fixed point notation (use -i instance to list only certain metrics and -r for raw values):<BR><B> +<BR> $ pmval -f 3 disk.partitions.write -a <FONT COLOR="#cc0000">acme.com</FONT>/20140902</B> +</TD></TR> +</TABLE> + +<TABLE WIDTH=100% BORDER=0 CELLPADDING=10 CELLSPACING=20> + <TR><TD BGCOLOR="#e2e2e2" WIDTH=70%><BR><IMG SRC="images/stepfwd_on.png" WIDTH=16 HEIGHT=16 BORDER=0> +Replay past disk write operations per partition in an archive with two second interval using fixed point notation between 9 AM and 10 AM (use full dates with syntax like @"2014-08-20 14:00:00"):<BR><B> +<BR> $ pmval -d -t 2sec -f 3 disk.partitions.write -S @09:00 -T @10:00 -a <FONT COLOR="#cc0000">acme.com</FONT>/20140902</B> +</TD></TR> +</TABLE> + +<TABLE WIDTH=100% BORDER=0 CELLPADDING=10 CELLSPACING=20> + <TR><TD BGCOLOR="#e2e2e2" WIDTH=70%><BR><IMG SRC="images/stepfwd_on.png" WIDTH=16 HEIGHT=16 BORDER=0> +Calculate average values of performance metrics in an archive between 9 AM / 10 AM using table like formatting including the time of minimum/maximum value and the actual minimum/maximum value:<BR><B> +<BR> $ pmlogsummary -HlfiImM -S @09:00 -T @10:00 <FONT COLOR="#cc0000">acme.com</FONT>/20140902 disk.partitions.write mem.freemem</B> +</TD></TR> +</TABLE> + +<TABLE WIDTH=100% BORDER=0 CELLPADDING=10 CELLSPACING=20> + <TR><TD BGCOLOR="#e2e2e2" WIDTH=70%><BR><IMG SRC="images/stepfwd_on.png" WIDTH=16 HEIGHT=16 BORDER=0> +Dump past CPU load, memory usage, and disk write operations per partition in an archive averaged over 10 minute interval with fixed columns between 9 AM and 10 AM:<BR><B> +<BR> $ pmdumptext -t 10m -i -l -S @09:00 -T @10:00 'kernel.all.load[1]' 'mem.util.used' 'disk.partitions.write' -a <FONT COLOR="#cc0000">acme.com</FONT>/20140902</B> +</TD></TR> +</TABLE> + +<TABLE WIDTH=100% BORDER=0 CELLPADDING=10 CELLSPACING=20> + <TR><TD BGCOLOR="#e2e2e2" WIDTH=70%><BR><IMG SRC="images/stepfwd_on.png" WIDTH=16 HEIGHT=16 BORDER=0> +Summarize differences in past performance metrics between two archives, comparing 2 AM / 3 AM in the first archive to 9 AM / 10 AM in the second archive (grep for '+' to quickly see values which were zero during the first period):<BR><B> +<BR> $ pmdiff -S @02:00 -T @03:00 -B @09:00 -E @10:00 <FONT COLOR="#cc0000">acme.com</FONT>/20140902 <FONT COLOR="#cc0000">acme.com</FONT>/20140901</B> +</TD></TR> +</TABLE> + +<TABLE WIDTH=100% BORDER=0 CELLPADDING=10 CELLSPACING=20> + <TR><TD BGCOLOR="#e2e2e2" WIDTH=70%><BR><IMG SRC="images/stepfwd_on.png" WIDTH=16 HEIGHT=16 BORDER=0> +Replay past system metrics in an archive in a top like window starting 9 AM (this needs a large window):<BR><B> +<BR> $ pmatop -S @09:00 -a <FONT COLOR="#cc0000">acme.com</FONT>/20140902</B> +</TD></TR> +</TABLE> + +<TABLE WIDTH=100% BORDER=0 CELLPADDING=10 CELLSPACING=20> + <TR><TD BGCOLOR="#e2e2e2" WIDTH=70%><BR><IMG SRC="images/stepfwd_on.png" WIDTH=16 HEIGHT=16 BORDER=0> +Dump past system metrics in a sar like fashion averaged over 10 minute interval in an archive between 9 AM and 10 AM:<BR><B> +<BR> $ pmstat -t 10m -S @09:00 -T @10:00 -a <FONT COLOR="#cc0000">acme.com</FONT>/20140902</B> +</TD></TR> +</TABLE> + +<TABLE WIDTH=100% BORDER=0 CELLPADDING=10 CELLSPACING=20> + <TR><TD BGCOLOR="#e2e2e2" WIDTH=70%><BR><IMG SRC="images/stepfwd_on.png" WIDTH=16 HEIGHT=16 BORDER=0> +Dump past system metrics in an iostat(1) like fashion averaged over one hour interval in an archive:<BR><B> +<BR> $ pmiostat -t 1h -a <FONT COLOR="#cc0000">acme.com</FONT>/20140902</B> +</TD></TR> +</TABLE> + +<TABLE WIDTH=100% BORDER=0 CELLPADDING=10 CELLSPACING=20> + <TR><TD BGCOLOR="#e2e2e2" WIDTH=70%><BR><IMG SRC="images/stepfwd_on.png" WIDTH=16 HEIGHT=16 BORDER=0> +Dump past system metrics in a free(1) like fashion at a specific historical time offset:<BR><B> +<BR> $ pcp -a <FONT COLOR="#cc0000">acme.com</FONT>/20140902 -O @10:02 free</B> +</TD></TR> +</TABLE> + +<TABLE WIDTH=100% BORDER=0 CELLPADDING=10 CELLSPACING=20> + <TR><TD BGCOLOR="#e2e2e2" WIDTH=70%><BR><IMG SRC="images/stepfwd_on.png" WIDTH=16 HEIGHT=16 BORDER=0> +Replay performance metrics with a GUI application with two second default interval in an archive between 9 AM and 10 AM. Use File->New Chart to select metrics to be included in a new view and use File->Open View to use a predefined view:<BR><B> +<BR> $ pmchart -t 2sec -S @09:00 -T @10:00 -a <FONT COLOR="#cc0000">acme.com</FONT>/20140902 -O @10:02 free</B> +</TD></TR> +</TABLE> + +<TABLE WIDTH=100% BORDER=0 CELLPADDING=10 CELLSPACING=20> + <TR><TD BGCOLOR="#e2e2e2" WIDTH=70%><BR><IMG SRC="images/stepfwd_on.png" WIDTH=16 HEIGHT=16 BORDER=0> +Merge several archives as a new combined archive (see the manual page how to write configuration file to collect only certain metrics):<BR><B> +<BR> $ pmlogextract <archive1> <archive2> <newarchive></B> +</TD></TR> +</TABLE> + +<a name="visual"></a> +<H3>Visualizing iostat and sar Data</H3> + +<P>iostat and sar data can be imported as PCP archives which then allows inspecting and visualizing the data with PCP tools. The iostat2pcp importer is in the pcp-import-iostat2pcp package and the sar2pcp importer is in the pcp-import-sar2pcp package. + +<TABLE WIDTH=100% BORDER=0 CELLPADDING=10 CELLSPACING=20> + <TR><TD BGCOLOR="#e2e2e2" WIDTH=70%><BR><IMG SRC="images/stepfwd_on.png" WIDTH=16 HEIGHT=16 BORDER=0> +Import iostat data to a new PCP archive and visualize it:<BR><B> +<BR> $ iostat -t -x 2 > iostat.out +<BR> $ iostat2pcp iostat.out iostat.pcp +<BR> $ pmchart -t 2sec -a iostat.pcp </B> +</TD></TR> +</TABLE> + +<TABLE WIDTH=100% BORDER=0 CELLPADDING=10 CELLSPACING=20> + <TR><TD BGCOLOR="#e2e2e2" WIDTH=70%><BR><IMG SRC="images/stepfwd_on.png" WIDTH=16 HEIGHT=16 BORDER=0> +Import sar data from an existing sar archive to a new PCP archive and visualize it:<BR><B> +<BR> $ sar2pcp /var/log/sa/sa15 sar.pcp +<BR> $ pmchart -2 2sec -a sar.pcp </B> +</TD></TR> +</TABLE> + +<a name="processes"></a> +<H1>Process Level Performance Monitoring</H1> + +<P>PCP provides details of each running process via the standard PCP interfaces and tools on the localhost but due to security and performance considerations, most of the process related information is not stored in archive logs by default. +<P>Custom application instrumentation is possible with the Memory Mapped Value (MMV) PMDA. + +<a name="processmon"></a> +<H3>Live and Retrospective Process Monitoring</H3> + +<TABLE WIDTH=100% BORDER=0 CELLPADDING=10 CELLSPACING=20> + <TR><TD BGCOLOR="#e2e2e2" WIDTH=70%><BR><IMG SRC="images/stepfwd_on.png" WIDTH=16 HEIGHT=16 BORDER=0> +Display all the available process related metrics:<BR><B> +<BR> $ pminfo proc</B> +</TD></TR> +</TABLE> + +<TABLE WIDTH=100% BORDER=0 CELLPADDING=10 CELLSPACING=20> + <TR><TD BGCOLOR="#e2e2e2" WIDTH=70%><BR><IMG SRC="images/stepfwd_on.png" WIDTH=16 HEIGHT=16 BORDER=0> +Monitor the number of open file descriptors of the process 1234:<BR><B> +<BR> $ pmval -t 2sec 'proc.fd.count[1234]'</B> +</TD></TR> +</TABLE> + +<TABLE WIDTH=100% BORDER=0 CELLPADDING=10 CELLSPACING=20> + <TR><TD BGCOLOR="#e2e2e2" WIDTH=70%><BR><IMG SRC="images/stepfwd_on.png" WIDTH=16 HEIGHT=16 BORDER=0> +Monitor the CPU time, memory usage (RSS), and the number of threads of the process 1234 (-host local: is a workaround needed for the time being):<BR><B> +<BR> $ pmdumptext -h local: -t 2sec 'proc.psinfo.utime[1234]' 'proc.memory.rss[1234]' 'proc.psinfo.threads[1234]'</B> +</TD></TR> +</TABLE> + +<TABLE WIDTH=100% BORDER=0 CELLPADDING=10 CELLSPACING=20> + <TR><TD BGCOLOR="#e2e2e2" WIDTH=70%><BR><IMG SRC="images/stepfwd_on.png" WIDTH=16 HEIGHT=16 BORDER=0> +Display all the available process related metrics in an archive:<BR><B> +<BR> $ pminfo proc -a <FONT COLOR="#cc0000">acme.com</FONT>/20140902</B> +</TD></TR> +</TABLE> + +<TABLE WIDTH=100% BORDER=0 CELLPADDING=10 CELLSPACING=20> + <TR><TD BGCOLOR="#e2e2e2" WIDTH=70%><BR><IMG SRC="images/stepfwd_on.png" WIDTH=16 HEIGHT=16 BORDER=0> +Display the number of running processes on 2014-08-20 14:00:<BR><B> +<BR> $ pmval -s 1 -S @"2014-08-20 14:00" proc.nprocs -a <FONT COLOR="#cc0000">acme.com</FONT>/20140820</B> +</TD></TR> +</TABLE> + +<a name="instrument"></a> +<H3>Application Instrumentation</H3> + +<P>Applications can be instrumented in the PCP world by using Memory Mapped Values (MMVs). pmdammv is a PMDA which exports application level performance metrics using memory mapped files. It offers an extremely low overhead instrumentation facility that is well-suited to long running, mission critical applications where it is desirable to have performance metrics and availability information permanently enabled. + +<P>Application to be instrumented with MMV need to be PCP MMV aware, APIs are available for several languages including C, C++, Perl, and Python. Java applications may use the separate <A HREF="https://code.google.com/p/parfait/">Parfait</A> class library for enabling MMV. + +<P>Instrumentation of unaltered Java applications is a known feature request and is planned for a not-too-distant release. + +<P>See the <A HREF="http://www.pcp.io/doc/pcp-programmers-guide.pdf">Performance Co-Pilot Programmer's Guide PDF</A> for more information about application instrumentation. + +<a name="pmie"></a> +<H1>Performance Metrics Inference</H1> + +<P>Performance Metrics Inference Engine (PMIE) can evaluate rules and generate alarms, run scripts, or automate system management tasks based on live or past performance metrics. + +<TABLE WIDTH=100% BORDER=0 CELLPADDING=10 CELLSPACING=20> + <TR><TD BGCOLOR="#e2e2e2" WIDTH=70%><BR><IMG SRC="images/stepfwd_on.png" WIDTH=16 HEIGHT=16 BORDER=0> To enable PMIE, just enable and start the service:<br><B> +<br> # chkconfig pmie on +<br> # service pmie start +</B></TD></TR> +</TABLE> + +<P>To enable the monitoring host to run PMIE for collector hosts, add each host to the /etc/pcp/pmie/control configuration file. + +<TABLE WIDTH=100% BORDER=0 CELLPADDING=10 CELLSPACING=20> + <TR><TD BGCOLOR="#e2e2e2" WIDTH=70%><BR><IMG SRC="images/stepfwd_on.png" WIDTH=16 HEIGHT=16 BORDER=0> Enable monitoring of metrics from remote host <B>acme.com</B>:<B> +<BR> # echo <FONT COLOR="#cc0000">acme.com</FONT> n PCP_LOG_DIR/pmie/<FONT COLOR="#cc0000">acme.com</FONT> -c config.<FONT COLOR="#cc0000">acme.com</FONT> +<BR> +<BR> # service pmie restart +</B></TD></TR> +</TABLE> + +<P>Some examples in plain English describing what could be done with PMIE: +<UL> +<LI>If the number of IP received packets exceeds a threshold run a script to adjust firewall rules to limit the incoming traffic +<LI>If 3 out of 4 consecutive samples taken every minute of disk operations exceeds a threshold between 9 AM and 5 PM send an email and write a system log message +<LI>If all hosts in a group have CPU load over a threshold for more than 10 minutes or they have more application processes running than a threshold limit generate an alarm and run a script to tune the application +</UL> + +<TABLE WIDTH=100% BORDER=0 CELLPADDING=10 CELLSPACING=20> + <TR><TD BGCOLOR="#e2e2e2" WIDTH=70%><BR><IMG SRC="images/stepfwd_on.png" WIDTH=16 HEIGHT=16 BORDER=0> +This example shows a PMIE script, checks its syntax, runs it against an archive, and prints a simple message if more than 5 GB of memory was in use between 9 AM and 10 AM using one minute sampling interval:<BR><B> +<BR> $ cat pmie.ex +<PRE> + bloated = ( mem.util.used > 5 Gbyte ) + + -> print "%v memory used on %h!"</PRE> +<BR> $ pmie -C pmie.ex +<BR> $ pmie -t 1min -c pmie.ex -S @09:00 -T @10:00 -a <FONT COLOR="#cc0000">acme.com</FONT>/20140820</B> +</TD></TR> +</TABLE> + + +<a name="web"></a> +<H1>PCP Web Services</H1> + +<P>A daemon for exporting PCP metrics using a REST web service (over HTTP/JSON) is also available. Use this for viewing or monitoring PCP metrics in a web browser - several web interfaces are becoming available (also via the pcp-webapi package) to make this a reality. + +<TABLE WIDTH=100% BORDER=0 CELLPADDING=10 CELLSPACING=20> + <TR><TD BGCOLOR="#e2e2e2" WIDTH=70%><BR><IMG SRC="images/stepfwd_on.png" WIDTH=16 HEIGHT=16 BORDER=0> To install the PCP web service, simply run:<br><B> +<br> # yum install pcp-webapi +<br> # chkconfig pmwebd on +<br> # service pmwebd start +</B></TD></TR> +</TABLE> + +<a name="pmwebd"></a> +<H3>Performance Metrics Web Daemon</H3> + +<P>Performance Metrics Web Daemon (PMWEBD) is a front-end to both PMCD and PCP archives, providing a JSON interface suitable for use by web-based tools wishing to access performance data over HTTP. Custom applications can access all the available PCP information using this method, including possible data generated by custom PMDAs. + +<a name="browse"></a> +<H3>Web Interface for Performance Metrics</H3> + +<P>A web browser interface for accessing PCP performance metrics is currently a work in progress. These web interfaces make PCP metrics available via your choice of <A HREF="http://grafana.org/">Grafana</A> or <A HREF="http://graphite.wikidot.com/">Graphite</A>. + +<P>Further details will be added here once this feature is available. + +<a name="custom"></a> +<H1>Customizing and Extending PCP</H1> + +<P>PCP PMDAs offer a way for administrators and developers to customize and extend the default PCP installation. The pcp-libs-devel package contains all the needed development related examples, headers, and libraries. New PMDAs can easily be added, below is a quick list of references for starting development: + +<UL> +<LI>Some examples exist below /var/lib/pcp/pmdas/ - the simple, sample, and txmon PMDAs are easy to read PMDAs.</LI> + <UL> + <LI>The simple PMDA provides implementations in C, Perl and Python.</LI> + </UL> +<LI>A simple command line monitor tool is /usr/share/pcp/demos/pmclient (C language).</LI> +<LI>Good initial Python monitor examples are /usr/libexec/pcp/bin/pcp/pcp-*.</LI> + <UL> + <LI>Slightly more complex examples are the pmiostat, pmatop, pmcollectl commands.</LI> + </UL> +<LI>The examples in the source tree under src/pmwebapi/jsdemos are helpful when developing a web application.</LI> +</UL> + +<a name="next"></a> +<H1>Additional Information</H1> + +<UL> +<LI><A HREF="http://pcp.io/">http://pcp.io/</A> - PCP home page +<LI><A HREF="http://pcp.io/presentations.html">http://pcp.io/presentations.html</A> - PCP Presentations +<LI><A HREF="http://pcp.io/doc/pcp-users-and-administrators-guide.pdf">http://pcp.io/doc/pcp-users-and-administrators-guide.pdf</A> - Performance Co-Pilot User's and Administrator's Guide PDF +<LI><A HREF="http://pcp.io/doc/pcp-programmers-guide.pdf">http://pcp.io/doc/pcp-programmers-guide.pdf</A> - Performance Co-Pilot Programmer's Guide PDF +</UL> + +<P><BR></P> +<HR> +<CENTER> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0> + <TR> <TD WIDTH=50%><P>Copyright © 2007-2010 <A HREF="http://www.aconex.com/"><FONT COLOR="#000060">Aconex</FONT></A><BR>Copyright © 2000-2004 <A HREF="http://www.sgi.com/"><FONT COLOR="#000060">Silicon Graphics Inc</FONT></P></TD> + <TD WIDTH=50%><P ALIGN=RIGHT><A HREF="http://pcp.io/"><FONT COLOR="#000060">PCP Site</FONT></A><BR>Copyright © 2012-2014 <A HREF="http://www.redhat.com/"><FONT COLOR="#000060">Red Hat</FONT></P></TD> </TR> +</TABLE> +</CENTER> +</BODY> +</HTML> diff --git a/man/html/howto.cpuperf.html b/man/html/howto.cpuperf.html new file mode 100644 index 0000000..31fc5d3 --- /dev/null +++ b/man/html/howto.cpuperf.html @@ -0,0 +1,430 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> +<!-- + (c) Copyright 2000-2004 Silicon Graphics Inc. All rights reserved. + 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 + http://creativecommons.org/licenses/by-sa/3.0/us/ . +--> +<HTML> +<HEAD> + <meta http-equiv="content-type" content="text/html; charset=utf-8"> + <meta http-equiv="content-style-type" content="text/css"> + <link href="pcpdoc.css" rel="stylesheet" type="text/css"> + <link href="images/pcp.ico" rel="icon" type="image/ico"> + <TITLE>Understanding system-level processor performance</TITLE> +</HEAD> +<BODY LANG="en-AU" TEXT="#000060" DIR="LTR"> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 STYLE="page-break-before: always"> + <TR> <TD WIDTH=64 HEIGHT=64><FONT COLOR="#000080"><A HREF="http://pcp.io/"><IMG SRC="images/pcpicon.png" NAME="pmcharticon" ALIGN=TOP WIDTH=64 HEIGHT=64 BORDER=0></A></FONT></TD> + <TD WIDTH=1><P> </P></TD> + <TD WIDTH=500><P VALIGN=MIDDLE ALIGN=LEFT><A HREF="index.html"><FONT COLOR="#cc0000">Home</FONT></A> · <A HREF="lab.pmchart.html"><FONT COLOR="#cc0000">Charts</FONT></A> · <A HREF="timecontrol.html"><FONT COLOR="#cc0000">Time Control</FONT></A></P></TD> + </TR> +</TABLE> +<H1 ALIGN=CENTER STYLE="margin-top: 0.48cm; margin-bottom: 0.32cm"><FONT SIZE=7>Understanding measures of system-level processor performance</FONT></H1> +<TABLE WIDTH=15% BORDER=0 CELLPADDING=5 CELLSPACING=10 ALIGN=RIGHT> + <TR><TD BGCOLOR="#e2e2e2"><IMG SRC="images/system-search.png" WIDTH=16 HEIGHT=16 BORDER=0> <I>Tools</I><BR><PRE> +pmchart +mpvis +sar +</PRE></TD></TR> +</TABLE> +<P>This chapter of the Performance Co-Pilot tutorial provides some hints +on how to interpret and understand the various measures of system-level +processor (CPU) performance.</P> +<P>All modern operating systems collect processor resource utilization at both +the <B>process</B>-level and the <B>system</B>-level. This tutorial relate specifically to the <B>system</B>-level metrics.</P> +<P>For an explanation of Performance Co-Pilot terms and acronyms, consult +the <A HREF="glossary.html">PCP glossary</A>.</P> + +<P><BR></P> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 BGCOLOR="#e2e2e2"> + <TR><TD WIDTH=100% BGCOLOR="#081c59"><P ALIGN=LEFT><FONT SIZE=5 COLOR="#ffffff"><B>How the system-level CPU time is computed</B></FONT></P></TD></TR> +</TABLE> +<P> +Both <I>sar</I> and Performance Co-Pilot (PCP) use a common collection +of system-level CPU performance instrumentation from the kernel. +This instrumentation is based upon statistical sampling of the state of <B>each</B> + CPU in the kernel's software clock interrupt routine which is commonly +called 100 times (HZ) per second on every CPU.</P> +<P> +At each observation a CPU is attributed a quantum of 10 milliseconds of +elapsed time to one of several counters based on the current state of +the code executing on that CPU.</P> +<P> +This sort of statistical sampling is subject to some anomalies, +particularly when activity is strongly correlated with the clock +interrupts, however the distribution of observations over several +seconds or minutes is often an accurate reflection of the true +distribution of CPU time. The kernel profiling mechanisms offer higher +resolution should that be required, however that is beyond the scope +of this document.</P> +<P> +The CPU state is determined by considering what the CPU was doing just +before the clock interrupt, as follows:</P> +<OL> + <LI> + If executing a <B>user</B> thread (i.e. above the kernel system + call interface for some process) then the state is CPU_USER. + <LI> + If executing a kernel interrupt thread, then the state is CPU_INTR. + <LI> + If executing a kernel thread waiting for a graphics event, then the + state is CPU_WAIT. + <LI> + If otherwise executing a kernel thread, then the state is CPU_KERNEL. + <LI> + If not executing a kernel thread and some I/O is pending, then the + state is CPU_WAIT. + <LI> + If not executing a kernel thread and no I/O is pending and some user + thread is paused waiting for memory to become available, then the state + is CPU_SXBRK. + <LI> + Otherwise the state is CPU_IDLE. +</OL> +<P> +These states are mutually exclusive and complete, so exactly one state +is assigned for each CPU at each clock interrupt.</P> +<P> +The kernel agent for PCP exports the following metrics:</P> +<TABLE BORDER="1"> + <CAPTION ALIGN="BOTTOM"><B>Table 1: Raw PCP CPU metrics</B></CAPTION> + <TR VALIGN="TOP"> + <TH>PCP Metric</TH> + <TH>Semantics</TH> + </TR> + <TR VALIGN="TOP"> + <TD><I><TT>kernel.all.cpu.user</TT></I></TD> + <TD>Time counted when in CPU_USER state.</TD> + </TR> + <TR VALIGN="TOP"> + <TD><I><TT>kernel.all.cpu.sys</TT></I></TD> + <TD>Time counted when in CPU_KERNEL state.</TD> + </TR> + <TR VALIGN="TOP"> + <TD><I><TT>kernel.all.cpu.intr</TT></I></TD> + <TD>Time counted when in CPU_INTR state.</TD> + </TR> + <TR VALIGN="TOP"> + <TD><I><TT>kernel.all.cpu.sxbrk</TT></I></TD> + <TD>Time counted when in CPU_SXBRK state (IRIX only).</TD> + </TR> + <TR VALIGN="TOP"> + <TD><I><TT>kernel.all.cpu.wait.total</TT></I></TD> + <TD>Time counted when in CPU_WAIT state (UNIX only).</TD> + </TR> + <TR VALIGN="TOP"> + <TD><I><TT>kernel.all.cpu.idle</TT></I></TD> + <TD>Time counted when in CPU_IDLE state.</TD> + </TR> +</TABLE> +<P> +These metrics are all "counters" in units of milliseconds +(cumulative since system boot time) so when displayed with most PCP +tools they are "rate converted" (sampled periodically and the +differences between consecutive values converted to time utilization in +units of milliseconds per second over the sample interval). Since the +raw values are aggregated across all CPUs, the time utilization for any +of the metrics above is in the range 0 to N*1000 for an N CPU system; +for some PCP tools this is reported as a percentage in the range 0 to +N*100 percent.</P> + +<TABLE WIDTH=100% BORDER=0 CELLPADDING=10 CELLSPACING=20> + <TR><TD BGCOLOR="#e2e2e2" WIDTH=70%><BR><IMG SRC="images/stepfwd_on.png" WIDTH=16 HEIGHT=16 BORDER=0> Using <I>pmchart</I> to display CPU activity (aggregated over all CPUs).<BR> +<PRE><B> +$ source /etc/pcp.conf +$ tar xzf $PCP_DEMOS_DIR/tutorials/cpuperf.tgz +$ pmchart -c CPU -t 2sec -O -0sec -a cpuperf/moomba.pmkstat +</B></PRE> +<BR> +This command will provide the interactive charts described here. +</TD></TR> +</TABLE> + +<P>On IRIX, the CPU_WAIT state is further subdivided into components describing +different types of "waiting":</P> +<OL> + <LI> + If executing a kernel thread waiting for a graphics context switch, + then the waiting classification W_GFXC is true. + <LI> + If executing a kernel thread waiting for a graphics FIFO operation to + complete, then the waiting classification W_GFXF is true. + <LI> + If not executing any thread and an I/O involving a block device (most + likely associated with a file system but independent of the CPU from + which the I/O was initiated), then the waiting classification W_IO is + true. + <LI> + If not executing any thread and an I/O involving a swap operation + (independent of the CPU from which the I/O was initiated), then the + waiting classification W_SWAP is true. + <LI> + If not executing any thread and an I/O involving a raw device is + pending (independent of the CPU from which the I/O was initiated), then + the waiting classification W_PIO is true. +</OL> +<P> +More than one of the group { W_IO, W_SWAP, W_PIO } can be true each +time, however this group and W_GFXC and W_GFXF are all mutually +exclusive. If the state is CPU_WAIT, then at least one of the +classifications must be true.</P> +<P> +The IRIX agent for PCP exports the following CPU "wait" +metrics, the sum of which approximately equals <I><TT>kernel.all.cpu.wait.total</TT></I>:</P> +<TABLE BORDER="1"> + <CAPTION ALIGN="BOTTOM"><B>Table 2: Raw PCP CPU wait metrics</B></CAPTION> + <TR VALIGN="TOP"> + <TH>PCP Metric</TH> + <TH>Semantics</TH> + </TR> + <TR VALIGN="TOP"> + <TD><I><TT>kernel.all.cpu.wait.gfxc</TT></I></TD> + <TD>Time counted when W_GFXC is true.</TD> + </TR> + <TR VALIGN="TOP"> + <TD><I><TT>kernel.all.cpu.wait.gfxf</TT></I></TD> + <TD>Time counted when W_GFXF is true.</TD> + </TR> + <TR VALIGN="TOP"> + <TD><I><TT>kernel.all.cpu.wait.io</TT></I></TD> + <TD>Time counted when W_IO is true.</TD> + </TR> + <TR VALIGN="TOP"> + <TD><I><TT>kernel.all.cpu.wait.pio</TT></I></TD> + <TD>Time counted when W_SWAP is true.</TD> + </TR> + <TR VALIGN="TOP"> + <TD><I><TT>kernel.all.cpu.wait.swap</TT></I></TD> + <TD>Time counted when W_PIO is true.</TD> + </TR> +</TABLE> +<P> +These metrics are all "counters" in units of milliseconds +(cumulative since system boot time) so when displayed with most PCP +tools they are "rate converted" (sampled periodically and the +differences between consecutive values converted to time utilization in +units of milliseconds per second over the sample interval). Since the +raw values are aggregated across all CPUs, the time utilization for any +of the metrics above is in the range 0 to N*1000 for an N CPU system; +for some PCP tools this is reported as a percentage in the range 0 to +N*100 percent.</P> +<P> +Note that for a multiprocessor system with one I/O pending, <B>all</B> + otherwise idle CPUs will be assigned the CPU_WAIT state. This may lead +to an over-estimate of the I/O wait time, as discussed in the +companion <A HREF="howto.diskperf.html">How to understand measures of +disk performance</A> document.</P> +<P> +In IRIX 6.5.2 additional instrumentation was added to help address the +wait time attribution by looking at the <B>number</B> of waiting +processes in various states, rather than the state of a CPU with +reference to the cardinality of the various sets of waiting processes. +The wait I/O queue length is defined as the number of processes +waiting on events corresponding to the classifications W_IO, W_SWAP or +W_PIO. The metrics shown in the table below are computed on only <B>one</B> + of the CPUs (the "clock-master") each clock interrupt.</P> +<TABLE BORDER="1"> + <CAPTION ALIGN="BOTTOM"><B>Table 3: Raw PCP wait I/O queue length + metrics</B></CAPTION> + <TR VALIGN="TOP"> + <TH>PCP Metric</TH> + <TH>Semantics</TH> + </TR> + <TR VALIGN="TOP"> + <TD><I><TT>kernel.all.waitio.queue</TT></I></TD> + <TD>Cumulative total of the wait I/O queue lengths, as observed + on each clock interrupt.</TD> + </TR> + <TR VALIGN="TOP"> + <TD><I><TT>kernel.all.waitio.occ</TT></I></TD> + <TD>Cumulative total of the number of times the wait I/O queue + length is greater than zero, as observed on each clock interrupt.</TD> + </TR> +</TABLE> +<P> +These metrics may be used with PCP tools as follows:</P> +<UL> + <LI> + Displaying <I><TT>kernel.all.waitio.queue</TT></I> with <I>pmval</I>, <I>pmdumptext</I>, <I>pmchart</I>, + etc. will display the time average of the wait I/O queue length + multiplied by the frequency of clock interrupts, i.e. by 100. + <LI> + Displaying <I><TT>kernel.all.waitio.occ</TT></I> with <I>pmval</I>, <I>pmdumptext</I>, <I>pmchart</I>, + etc. will display the probability that the wait I/O queue is not empty + multiplied by the frequency of clock interrupts, i.e. by 100. This + value (converted to a percentage) is reported as <I><TT>%wioocc</TT></I> + by the <B>-q</B> option of <I>sar.</I> + <LI> + Using <I>pmie</I> with the expression<BR> + <I><TT>kernel.all.waitio.queue / kernel.all.waitio.occ</TT></I><BR> + will report the stochastic average of the wait I/O queue length, + conditional upon the queue not being empty. This value is reported as <I><TT>wioq-sz</TT></I> + by the <B>-q</B> option of <I>sar.</I> +</UL> + +<P><BR></P> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 BGCOLOR="#e2e2e2"> + <TR><TD WIDTH=100% BGCOLOR="#081c59"><P ALIGN=LEFT><FONT SIZE=5 COLOR="#ffffff"><B>The per-CPU variants</B></FONT></P></TD></TR> +</TABLE> +<P> +Inside the kernel, most of the metrics described above are +accumulated per-CPU for reasons of efficiency (to reduce the locking +overheads and minimize dirty cache-line traffic).</P> +<P> +PCP exports the per-CPU versions of the system-wide metrics with metric +names formed by replacing <B><I><TT>all</TT></I></B> by <B><I><TT>percpu</TT></I></B>, +e.g. <I><TT>kernel.percpu.cpu.user</TT></I>.</P> +<P> + +<TABLE WIDTH=100% BORDER=0 CELLPADDING=10 CELLSPACING=20> + <TR><TD BGCOLOR="#e2e2e2" WIDTH=70%><BR><IMG SRC="images/stepfwd_on.png" WIDTH=16 HEIGHT=16 BORDER=0> The <I>mpvis</I> tool provides 3-D visualization of these per-CPU metrics.<PRE><B> +$ mpvis -a cpuperf/babylon.percpu +</B></PRE> +<BR> +When the window is shown, use the <A HREF="timecontrol.html">PCP Archive Time Control</A> dialog to scroll through the archive (Fast Forward). +</TD></TR> +</TABLE> + +<P><BR></P> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 BGCOLOR="#e2e2e2"> + <TR><TD WIDTH=100% BGCOLOR="#081c59"><P ALIGN=LEFT><FONT SIZE=5 COLOR="#ffffff"><B>Reconciling sar -u and PCP CPU performance metrics</B></FONT></P></TD></TR> +</TABLE> +<P> +The <I>sar</I> metrics are scaled based on the number of CPUs and +expressed in percentages, PCP metrics are in units of milliseconds per +second after rate conversion; this explains the PCP metric <I><TT>hinv.ncpu</TT></I> + and the constants 100 and 1000 in the expressions below.</P> +<P> +When run with a <B>-u</B> option, <I>sar</I> reports the following:</P> +<TABLE BORDER="1"> + <CAPTION ALIGN="BOTTOM"><B>Table 3: PCP and sar metric equivalents</B></CAPTION> + <TR> + <TH><I>sar</I><BR> + metric</TH> + <TH>PCP equivalent (assuming rate conversion)</TH> + </TR> + <TR VALIGN="TOP"> + <TD><I><TT>%usr</TT></I></TD> + <TD>100 * <I><TT>kernel.all.cpu.user</TT></I> / (<I><TT>hinv.ncpu </TT></I>* + 1000)</TD> + </TR> + <TR VALIGN="TOP"> + <TD><I><TT>%sys</TT></I></TD> + <TD>100 * <I><TT>kernel.all.cpu.sys</TT></I> / (<I><TT>hinv.ncpu </TT></I>* + 1000)</TD> + </TR> + <TR VALIGN="TOP"> + <TD><I><TT>%intr</TT></I></TD> + <TD>100 * <I><TT>kernel.all.cpu.intr</TT></I> / (<I><TT>hinv.ncpu </TT></I>* + 1000)</TD> + </TR> + <TR VALIGN="TOP"> + <TD><I><TT>%wio</TT></I></TD> + <TD>100 * <I><TT>kernel.all.cpu.wait.total</TT></I> / (<I><TT>hinv.ncpu </TT></I>* + 1000)</TD> + </TR> + <TR VALIGN="TOP"> + <TD><I><TT>%idle</TT></I></TD> + <TD>100 * <I><TT>kernel.all.cpu.idle</TT></I> / (<I><TT>hinv.ncpu </TT></I>* + 1000)</TD> + </TR> + <TR VALIGN="TOP"> + <TD><I><TT>%sbrk</TT></I></TD> + <TD>100 * <I><TT>kernel.all.cpu.sxbrk </TT></I>/ (<I><TT>hinv.ncpu </TT></I>* + 1000)</TD> + </TR> + <TR VALIGN="TOP"> + <TD><I><TT>%wfs</TT></I></TD> + <TD>100 * <I><TT>kernel.all.cpu.wait.io</TT></I> / <I><TT>kernel.all.cpu.wait.total</TT></I></TD> + </TR> + <TR VALIGN="TOP"> + <TD><I><TT>%wswp</TT></I></TD> + <TD>100 * <I><TT>kernel.all.cpu.wait.swap</TT></I> / <I><TT>kernel.all.cpu.wait.total</TT></I></TD> + </TR> + <TR> + <TD><I><TT>%wphy</TT></I></TD> + <TD>100 * <I><TT>kernel.all.cpu.wait.pio</TT></I> / <I><TT>kernel.all.cpu.wait.total</TT></I></TD> + </TR> + <TR> + <TD><I><TT>%wgsw</TT></I></TD> + <TD>100 * <I><TT>kernel.all.cpu.wait.gfxc</TT></I> / <I><TT>kernel.all.cpu.wait.total</TT></I></TD> + </TR> + <TR> + <TD><I><TT>%wfif</TT></I></TD> + <TD>100 * <I><TT>kernel.all.cpu.wait.gfxf</TT></I> / <I><TT>kernel.all.cpu.wait.total</TT></I></TD> + </TR> +</TABLE> + +<P><BR></P> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 BGCOLOR="#e2e2e2"> + <TR><TD WIDTH=100% BGCOLOR="#081c59"><P ALIGN=LEFT><FONT SIZE=5 COLOR="#ffffff"><B>The load average</B></FONT></P></TD></TR> +</TABLE> +<P> +The "load average" is reported by <I>uptime</I>, <I>top</I>, +etc. and the PCP metric <I><TT>kernel.all.load</TT></I>.</P> +<P> +The load average is an indirect measure of the demand for CPU +resources. It is calculated using the previous load average (<I>load</I>) +and the number of currently runnable processes (<I>nrun</I>) and an +exponential dampening expression, e.g. for the "1 minute" +average, the expression is:</P> +<PRE> +load = exp(-5/60) * load + (1 - exp(-5/60)) * nrun +</PRE> +<P> +The three load averages use different exponential constants and are all +re-computed every 5 seconds.</P> +<P> +<I>nrun</I> is computed as follows:</P> +<OL> + <LI> + Inspect every process. + <LI> + If the process is not likely to be runnable in the near future (state + not SRUN), ignore it. + <LI> + Inspect every thread of the process. + <LI> + If the thread is sleeping and not currently expanding its address space + (state not SXBRK) and not in a long-term sleep, increment <I>nrun.</I> + + <LI> + If the thread is stopped, ignore it. + <LI> + Otherwise if the thread is not "weightless" (being ignored by + the scheduler), increment <I>nrun.</I> +</OL> +<P> +Note that the "run queue length" (a variant of which is +reported by the <B>-q</B> option of <I>sar</I>) counts processes using +a similar, but not identical algorithm:</P> +<OL> + <LI> + Inspect every process. + <LI> + If the process is not likely to be runnable in the near future (state + not SRUN), ignore it. + <LI> + Inspect every thread of the process. + <LI> + If the thread is sleeping and not currently expanding its address space + (state not SXBRK), ignore it + <LI> + If the thread is stopped, ignore it. + <LI> + Otherwise increment the "run queue length". +</OL> + +<P><BR></P> +<HR> +<CENTER> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0> + <TR> <TD WIDTH=50%><P>Copyright © 2007-2010 <A HREF="http://www.aconex.com/"><FONT COLOR="#000060">Aconex</FONT></A><BR>Copyright © 2000-2004 <A HREF="http://www.sgi.com/"><FONT COLOR="#000060">Silicon Graphics Inc</FONT></P></TD> + <TD WIDTH=50%><P ALIGN=RIGHT><A HREF="http://pcp.io/"><FONT COLOR="#000060">PCP Site</FONT></A><BR>Copyright © 2012-2014 <A HREF="http://www.redhat.com/"><FONT COLOR="#000060">Red Hat</FONT></P></TD> </TR> +</TABLE> +</CENTER> +</BODY> +</HTML> diff --git a/man/html/howto.diskmodel.html b/man/html/howto.diskmodel.html new file mode 100644 index 0000000..ae73aaa --- /dev/null +++ b/man/html/howto.diskmodel.html @@ -0,0 +1,163 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> +<HTML> +<HEAD> + <meta http-equiv="content-type" content="text/html; charset=utf-8"> + <meta http-equiv="content-style-type" content="text/css"> + <link href="pcpdoc.css" rel="stylesheet" type="text/css"> + <link href="images/pcp.ico" rel="icon" type="image/ico"> + <TITLE>Comparing Storage Performance</TITLE> +</HEAD> +<BODY LANG="en-AU" TEXT="#000060" DIR="LTR"> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 STYLE="page-break-before: always"> + <TR> <TD WIDTH=64 HEIGHT=64><FONT COLOR="#000080"><A HREF="http://pcp.io/"><IMG SRC="images/pcpicon.png" NAME="pmcharticon" ALIGN=TOP WIDTH=64 HEIGHT=64 BORDER=0></A></FONT></TD> + <TD WIDTH=1><P> </P></TD> + <TD WIDTH=500><P VALIGN=MIDDLE ALIGN=LEFT><A HREF="index.html"><FONT COLOR="#cc0000">Home</FONT></A> · <A HREF="lab.pmchart.html"><FONT COLOR="#cc0000">Charts</FONT></A> · <A HREF="timecontrol.html"><FONT COLOR="#cc0000">Time Control</FONT></A></P></TD> + </TR> +</TABLE> +<H1 ALIGN=CENTER STYLE="margin-top: 0.48cm; margin-bottom: 0.32cm"><FONT SIZE=7>Comparing storage performance</FONT></H1> +<TABLE WIDTH=15% BORDER=0 CELLPADDING=5 CELLSPACING=10 ALIGN=RIGHT> + <TR><TD BGCOLOR="#e2e2e2"><IMG SRC="images/system-search.png" WIDTH=16 HEIGHT=16 BORDER=0> <I>Tools</I><BR><PRE> +pmlogger +pmlogsummary +PCP::LogSummary +pmchart +pmafm +perl +fio +</PRE></TD></TR> +</TABLE> +<P>When comparing multiple storage (or any) systems in terms of performance, it is often useful to create a simulation of the load observed in the actual production environment. Reasons for doing this mainly centre around the difficulty in running a production load in the evaluation environment. For example, recreating databases, filesystems, sanitising user data, installing and configuring (possibly licensed) software, perhaps needing large amounts of time from specialists skilled in those areas - these can all be prohibitive. In such situations it is ideal to model or simulate a workload rather than using an actual production load. When comparing a new system to an existing one, or comparing competing technologies from different vendors, a quick way to run a simulated workload is invaluable. +</P> +<P>PCP provides handy tools for providing confidence that a simulation matches reality. Here we demonstrate several of these tools and techniques for applying them toward modelling a workload, using an iSCSI storage comparison as an example. We will also use the open source <i><b>fio</b></i> utility to generate the actual I/O workload, once we've used PCP to characterise it, and finally use PCP again to verify the simulations produced. +</P> + +<P><BR></P> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 BGCOLOR="#e2e2e2"> + <TR><TD WIDTH=100% BGCOLOR="#081c59"><P ALIGN=LEFT><FONT SIZE=5 COLOR="#ffffff"><B>Step 1 - Gathering Baseline Data</B></FONT></P></TD></TR> +</TABLE> +<P>For this example we will be using data gathered from two production systems - a NAS machine and a database.</P> +<P>These are extracts from production logs that showed a typical load for those two machines during business hours. The data was gathered using <i>pmlogger</i> and the archive management scripts <i>pmlogger_daily</i>. It was reduced to only the metrics of interest for our evaluation using <i>pmlogextract</i>. Setting up and managing logging of performance data in this way is demonstrated <A HREF="lab.pmlogger.html">elsewhere</A>.</P> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=10 CELLSPACING=20> + <TR><TD BGCOLOR="#e2e2e2" WIDTH=70%><BR><IMG SRC="images/stepfwd_on.png" WIDTH=16 HEIGHT=16 BORDER=0> If you have the tutorial installed, in a command shell enter:<BR> +<PRE><B> +$ source /etc/pcp.conf +<BR> +$ tar xzf $PCP_DEMOS_DIR/tutorials/diskmodel.tgz +<BR> +$ cd diskmodel +<BR> +$ echo * +<BR><i> model.fio model.pl model.view model.xls</i> +<BR><i> dbdata.0 dbdata.index dbdata.meta</i> +<BR><i> nasdata.0 nasdata.index nasdata.meta</i> +<BR><i> nasread.out naswrite.out</i> +<BR> +$ pmafm model.folio run pmchart -t 15 -c model.view +<BR> +</B></PRE> +This command will provide the interactive charts seen here... +</TD> +<TD><P VALIGN=MIDDLE ALIGN=RIGHT><CENTER><BR><IMG ALIGN=RIGHT SRC="images/model_dbload.png" BORDER=0></CENTER></P></TD> +</TR> +</TABLE> +<P>As an aside, the NAS is a Redhat Enterprise Linux 5 machine serving NFS, the database is running Windows Server 2008 and SQL Server 2008 - but this does not really matter for our modelling purposes.</P> +<P><BR></P> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 BGCOLOR="#e2e2e2"> + <TR><TD WIDTH=100% BGCOLOR="#081c59"><P ALIGN=LEFT><FONT SIZE=5 COLOR="#ffffff"><B>Step 2 - Baseline Summary</B></FONT></P></TD></TR> +</TABLE> +<P>Next we use the <i><b>pmlogsummary</b></i> utility to extract a statistical summary of key disk metrics. We do this indirectly, in this example, using the <i>PCP::LogSummary</i> Perl module and a custom wrapper script (<A HREF="diskmodel/model.pl">model.pl</A>). This generates a spreadsheet with all of the key aspects of performance that our model must aim to reproduce. +</P> +<P>As part of this phase of analysis, we must identify the key aspects of +the workload we are analysing and break it down into its components, +using information we know about the modelled environment. This +level of breakdown is useful, as it lets us make informed statements later +about how well the model simulates each component. +</P> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=10 CELLSPACING=10> +<TR> +<TD><P VALIGN=MIDDLE ALIGN=LEFT><CENTER><BR><IMG ALIGN=LEFT SRC="images/model_nasload.png" BORDER=0></CENTER></P></TD> +<TD><P> In this example we have a fairly simple NAS workload where files are +only ever written once (and never updated), and subsequently read many +times over, and never deleted. We identify typical file sizes through +what we know about our production environment, and we know that we are +data dominated rather than metadata dominated - so the model will focus +on issuing sequential reads and writes to different files, using a mix +of I/O sizes that produce the averages and ratios identified in the +spreadsheet, and will never overwrite or truncate files. </P> +</TD></TR> +<TR> +<TD><P> In the database case, we identify two workloads, with a total of three +components. There is an interactive load (many small random reads +and regular log writes) and also a reporting (business intelligence) +load. The interactive load is constant, has read and write components - the +write components include log writes once every minute, the reads are +constant and small (identified in the spreadsheet). The reporting load +is completely read dominated (table scans). The regular background write +activity does proceed during this time, so our model will cater for this +characteristic by generating the log write traffic separately and then +using that in both loads. </P> +</TD> +<TD><P VALIGN=MIDDLE ALIGN=RIGHT><CENTER><BR><IMG ALIGN=RIGHT SRC="images/model_biload.png" BORDER=0></CENTER></P></TD> +</TABLE> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=10 CELLSPACING=20> + <TR><TD BGCOLOR="#e2e2e2"><IMG SRC="images/stepfwd_on.png" WIDTH=16 HEIGHT=16 BORDER=0> Examine the (trivial) <A HREF="diskmodel/model.pl">model.pl</A> Perl script and note its basic control flow:<BR><PRE> +<B>$ cat model.pl</B> +# Setup some spreadsheet metadata - fonts, colors, etc +# Create a worksheet, configure a few columns +# Write data - starting at row 0 and column 0, moving across and down +</PRE> +If you have the PCP::LogSummary and SpreadSheet::WriteExcel Perl modules installed, run it: +<BR><PRE> +<B>$ perl model.pl</B> +</PRE> +</TD></TR> +</TABLE> +<CENTER><IMG SRC="images/model_spreadsheet.png" WIDTH=912 HEIGHT=552 BORDER=1></CENTER> + +<P><BR></P> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 BGCOLOR="#e2e2e2"> + <TR><TD WIDTH=100% BGCOLOR="#081c59"><P ALIGN=LEFT><FONT SIZE=5 COLOR="#ffffff"><B>Step 3 - Simulation</B></FONT></P></TD></TR> +</TABLE> +<P>Armed with our workload summary, we will begin to produce a model. To generate I/O we will use the Linux <i><b>fio</i></b> utility. This reads a workload description from a configuration file, preallocates files in a test directory, then runs the defined workload, and produces a statistical summary of the I/O characteristics observed. In our case, where we are planning to compare different vendors storage, we are particular interested in the I/O latency characteristics while running our different workloads, and to a lesser extent the throughput and IOPS numbers - these should be constant thanks to our workload generator and as long as they are achieved, its the latency statistics that concern us (maximum, average, standard deviation). +</P> +<P>The <i><b>fio</b></i> configuration file which generates our workloads is <A HREF="diskmodel/model.fio">model.fio</A>. While testing the model, the I/O submission patterns have been monitored using the same techniques as before to ensure the generated load matches as closely as possible with production - this was an iterative process, fiddling <B>fio</B> knobs until good matches were achieved. </P> +<P>Below are an extract of the results, highlighting some of the statistics that are of particular interest in our scenario. These numbers suggest we have matched up with our production load from the spreadsheet (IOPs and throughput) and the latency numbers give good points of comparison when we run the model against other configurations. +</P> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=10 CELLSPACING=20> + <TR><TD BGCOLOR="#e2e2e2">Extracts from <A HREF="diskmodel/nasread.out">nasread.out</A> and <A HREF="diskmodel/nasread.out">naswrite.out</A><BR> +<PRE> + Description : [NAS reads workload model] + read : io=739MB, bw=<B>2,523KB/s</B>, iops=<B>78</B>, runt=300003msec + clat (usec): min=190, max=176K, avg=3343.45, stdev=2480.24 + lat (usec): min=191, max=176K, avg=3344.00, stdev=2480.24 + bw (KB/s) : min= 2301, max= 2808, per=25.02%, avg=2525.62, stdev=40.32 + ... + Description : [NAS writes workload model] + write: io=361MB, bw=<B>1,233KB/s</B>, iops=<B>37</B>, runt=300026msec + clat (usec): min=276, max=1,325K, avg=2721.65, stdev=47070.32 + lat (usec): min=277, max=1,325K, avg=2722.20, stdev=47070.32 + bw (KB/s) : min= 34, max= 4486, per=25.12%, avg=1239.08, stdev=178.78 +</PRE> +</TABLE> + +<P><BR></P> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 BGCOLOR="#e2e2e2"> + <TR><TD WIDTH=100% BGCOLOR="#081c59"><P ALIGN=LEFT><FONT SIZE=5 COLOR="#ffffff"><B>Step 4 - Profit!</B></FONT></P></TD></TR> +</TABLE> +<P>Now that we have an easily reproducible workload, we can throw it at any number of different devices (different vendors), configurations (different RAID configurations, with snapshots) and have a reasonable level of confidence that observations will resemble what would happen in production. +</P> +<P>Note that the latency numbers that <B><I>fio</I></B> has calculated for +us are excellent indicators - if we did not have these, we could make use +of the device utilisation PCP metrics (<i>disk.dev.avactive</i> or +<i>disk.dev.idle</i>) as alternate comparison points.</P> + +<P><BR></P> +<HR> +<CENTER> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0> + <TR> <TD WIDTH=50%><P>Copyright © 2007-2010 <A HREF="http://www.aconex.com/"><FONT COLOR="#000060">Aconex</FONT></A><BR>Copyright © 2000-2004 <A HREF="http://www.sgi.com/"><FONT COLOR="#000060">Silicon Graphics Inc</FONT></P></TD> + <TD WIDTH=50%><P ALIGN=RIGHT><A HREF="http://pcp.io/"><FONT COLOR="#000060">PCP Site</FONT></A><BR>Copyright © 2012-2014 <A HREF="http://www.redhat.com/"><FONT COLOR="#000060">Red Hat</FONT></P></TD> </TR> +</TABLE> +</CENTER> +</BODY> +</HTML> diff --git a/man/html/howto.diskperf.html b/man/html/howto.diskperf.html new file mode 100644 index 0000000..ffedfa0 --- /dev/null +++ b/man/html/howto.diskperf.html @@ -0,0 +1,754 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> +<!-- + (c) Copyright 2000-2004 Silicon Graphics Inc. All rights reserved. + 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 + http://creativecommons.org/licenses/by-sa/3.0/us/ . +--> +<HTML> +<HEAD> + <meta http-equiv="content-type" content="text/html; charset=utf-8"> + <meta http-equiv="content-style-type" content="text/css"> + <link href="pcpdoc.css" rel="stylesheet" type="text/css"> + <link href="images/pcp.ico" rel="icon" type="image/ico"> + <TITLE>How to understand disk performance</TITLE> +</HEAD> +<BODY LANG="en-AU" TEXT="#000060" DIR="LTR"> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 STYLE="page-break-before: always"> + <TR> <TD WIDTH=64 HEIGHT=64><FONT COLOR="#000080"><A HREF="http://pcp.io/"><IMG SRC="images/pcpicon.png" NAME="pmcharticon" ALIGN=TOP WIDTH=64 HEIGHT=64 BORDER=0></A></FONT></TD> + <TD WIDTH=1><P> </P></TD> + <TD WIDTH=500><P VALIGN=MIDDLE ALIGN=LEFT><A HREF="index.html"><FONT COLOR="#cc0000">Home</FONT></A> · <A HREF="lab.pmchart.html"><FONT COLOR="#cc0000">Charts</FONT></A> · <A HREF="timecontrol.html"><FONT COLOR="#cc0000">Time Control</FONT></A></P></TD> + </TR> +</TABLE> +<H1 ALIGN=CENTER STYLE="margin-top: 0.48cm; margin-bottom: 0.32cm"><FONT SIZE=7>How to understand measures of disk performance</FONT></H1> +<TABLE WIDTH=15% BORDER=0 CELLPADDING=5 CELLSPACING=10 ALIGN=RIGHT> + <TR><TD BGCOLOR="#e2e2e2"><IMG SRC="images/system-search.png" WIDTH=16 HEIGHT=16 BORDER=0> <I>Tools</I><BR><PRE> +pmchart +sar +</PRE></TD></TR> +</TABLE> +<P>This chapter of the Performance Co-Pilot tutorial provides some hints +on how to interpret and understand the various measures of disk +performance.</P> +<P>For an explanation of Performance Co-Pilot terms and acronyms, consult +the <A HREF="glossary.html">PCP glossary</A>.</P> + +<P><BR></P> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 BGCOLOR="#e2e2e2"> + <TR><TD WIDTH=100% BGCOLOR="#081c59"><P ALIGN=LEFT><FONT SIZE=5 COLOR="#ffffff"><B>Reconciling sar -d and PCP disk performance metrics</B></FONT></P></TD></TR> +</TABLE> +<P> +Both <I>sar</I> and Performance Co-Pilot (PCP) use a common collection +of disk performance instrumentation from the block layer in the kernel, +however the disk performance metrics provided by <I>sar</I> and PCP +differ in their derivation and semantics. This document +is an attempt to explain these differences. </P> +<P> +It is convenient to define the ``response time'' to be the time to +complete a disk operation as the sum of the time spent:</P> +<UL> + <LI> + entering the read() or write() system call and set up for an I/O + operation (time here is CPU bound and is assumed to be negligible per + I/O) + <LI> + in a queue of pending requests waiting to be handed to the device + controller (the ``queue time'') + <LI> + the time between the request being handed to the device controller and + the end of transfer interrupt (the ``(device) service time''), + typically composed of delays due to request scheduling at the + controller, bus arbitration, possible seek time, rotational latency, + data transfer, etc. + <LI> + time to process the end of transfer interrupt, housekeeping at the end + of an I/O operation and return from the read() or write() system call + (time here is CPU bound and also assumed to be negligible per I/O) +</UL> +<P> +Note that while the CPU time per I/O is assumed to be small in +relationship to the times involving operations at the device level, +when the system-wide I/O rate is high (and it could be tens of +thousands of I/Os per second on a very large configuration), the <B>aggregate</B> + CPU demand to support this I/O activity may be significant.</P> +<P> +The kernel agents for PCP export the following metrics for each disk spindle:</P> +<TABLE BORDER="1"> + <CAPTION ALIGN="BOTTOM"><B>Table 1: Raw PCP disk metrics</B></CAPTION> + <TR VALIGN="TOP"> + <TH>Metric</TH> + <TH>Units</TH> + <TH>Semantics</TH> + </TR> + <TR VALIGN="TOP"> + <TD><I><TT>disk.dev.read</TT></I></TD> + <TD>number</TD> + <TD>running total of <B>read</B> I/O requests since boot time</TD> + </TR> + <TR VALIGN="TOP"> + <TD><I><TT>disk.dev.write</TT></I></TD> + <TD>number</TD> + <TD>running total of <B>write</B> I/O requests since boot time</TD> + </TR> + <TR VALIGN="TOP"> + <TD><I><TT>disk.dev.total</TT></I></TD> + <TD>number</TD> + <TD>running total of I/O requests since boot time, equals <I><TT>disk.dev.read</TT></I> + + <I><TT>disk.dev.write</TT></I></TD> + </TR> + <TR VALIGN="TOP"> + <TD><I><TT>disk.dev.blkread</TT></I></TD> + <TD>number</TD> + <TD>running total of data <B>read</B> since boot time in units + of 512-byte blocks</TD> + </TR> + <TR VALIGN="TOP"> + <TD><I><TT>disk.dev.blkwrite</TT></I></TD> + <TD>number</TD> + <TD>running total of data <B>written</B> since boot time in + units of 512-byte blocks</TD> + </TR> + <TR VALIGN="TOP"> + <TD><I><TT>disk.dev.blktotal</TT></I></TD> + <TD>number</TD> + <TD>running total of data <B>read</B> or <B>written</B> since + boot time in units of 512-bytes, equals <I><TT>disk.dev.blkread + + disk.dev.blkwrite</TT></I></TD> + </TR> + <TR> + <TD><I><TT>disk.dev.read_bytes</TT></I></TD> + <TD>Kbytes</TD> + <TD>running total of data <B>read</B> since boot time in units + of Kbytes</TD> + </TR> + <TR> + <TD><I><TT>disk.dev.write_bytes</TT></I></TD> + <TD>Kbytes</TD> + <TD>running total of data <B>written</B> since boot time in + units of Kbytes</TD> + </TR> + <TR> + <TD><I><TT>disk.dev.bytes</TT></I></TD> + <TD>Kbytes</TD> + <TD>running total of data <B>read</B> or <B>written</B> since + boot time in units of Kbytes, equals <I><TT>disk.dev.read_bytes + + disk.dev.write_bytes</TT></I></TD> + </TR> + <TR VALIGN="TOP"> + <TD><I><TT>disk.dev.active</TT></I></TD> + <TD>milliseconds</TD> + <TD>running total (milliseconds since boot time) of time this + device has been busy servicing at least one I/O request</TD> + </TR> + <TR VALIGN="TOP"> + <TD><I><TT>disk.dev.response</TT></I></TD> + <TD>milliseconds</TD> + <TD>running total (milliseconds since boot time) of the + response time for all completed I/O requests</TD> + </TR> +</TABLE> +<P> +These metrics are all "counters" so when displayed with most +PCP tools, they are sampled periodically and the differences between +consecutive values converted to rates or time utilization over the +sample interval as follows:</P> +<TABLE BORDER="1"> + <CAPTION ALIGN="BOTTOM"><B>Table 2: PCP disk metrics as reported by + most PCP tools</B></CAPTION> + <TR VALIGN="TOP"> + <TH>Metric</TH> + <TH>Units</TH> + <TH>Semantics</TH> + </TR> + <TR VALIGN="TOP"> + <TD><I><TT>disk.dev.read</TT></I></TD> + <TD>number per second</TD> + <TD><B>read</B> I/O requests per second (or <B>read</B> IOPS)</TD> + </TR> + <TR VALIGN="TOP"> + <TD><I><TT>disk.dev.write</TT></I></TD> + <TD>number per second</TD> + <TD><B>write</B> I/O requests per second (or <B>write</B> IOPS)</TD> + </TR> + <TR VALIGN="TOP"> + <TD><I><TT>disk.dev.total</TT></I></TD> + <TD>number per second</TD> + <TD>I/O requests per second (or IOPS)</TD> + </TR> + <TR VALIGN="TOP"> + <TD><I><TT>disk.dev.blkread</TT></I></TD> + <TD>number per second</TD> + <TD>2 * (Kbytes <B>read</B> per second)</TD> + </TR> + <TR VALIGN="TOP"> + <TD><I><TT>disk.dev.blkwrite</TT></I></TD> + <TD>number per second</TD> + <TD>2 * (Kbytes <B>written </B>per second)</TD> + </TR> + <TR VALIGN="TOP"> + <TD><I><TT>disk.dev.blktotal</TT></I></TD> + <TD>number per second</TD> + <TD>2 * (Kbytes <B>read</B> or <B>written</B> per second)</TD> + </TR> + <TR> + <TD><I><TT>disk.dev.read_bytes</TT></I></TD> + <TD>Kbytes per second</TD> + <TD>Kbytes <B>read</B> per second</TD> + </TR> + <TR> + <TD><I><TT>disk.dev.write_bytes</TT></I></TD> + <TD>Kbytes per second</TD> + <TD>Kbytes <B>written </B>per second</TD> + </TR> + <TR> + <TD><I><TT>disk.dev.bytes</TT></I></TD> + <TD>Kbytes per second</TD> + <TD>Kbytes <B>read</B> or <B>written</B> per second</TD> + </TR> + <TR VALIGN="TOP"> + <TD><I><TT>disk.dev.active</TT></I></TD> + <TD>time utilization</TD> + <TD>fraction of time device was "busy" over the + sample interval (either in the range 0.0-1.0 or expressed as a + percentage in the rance 0-100); in this context "busy" means + servicing one or more I/O requests</TD> + </TR> + <TR VALIGN="TOP"> + <TD><I><TT>disk.dev.response</TT></I></TD> + <TD>time utilization</TD> + <TD>time average of the response time over the interval; this + is a slightly strange metric in that values larger than 1.0 (or 100%) + imply either device saturation, or controller saturation or a very + ``bursty'' request arrival pattern -- in isolation there is <B>no + sensible interpretation</B> of the rate converted value + this metric </TD> + </TR> +</TABLE> +<P> +The <I>sar</I> metrics <I><TT>avque</TT></I>, <I><TT>avwait</TT></I> + and <I><TT>avserv</TT></I> are subject to widespread +misinterpretation, and so warrant some special explanation. They may be +understood with the aid of a simple illustrative example. Consider the +following snapshot of disk activity in which the response time has been +simplified to be a multiple of 10 milliseconds for each I/O operation +over a 100 millisecond sample interval (this is an unlikely +simplification, but makes the arithmetic easier).</P> +<CENTER><P ALIGN="CENTER"> +<IMG SRC="images/sar-d.png" WIDTH="529" HEIGHT="152"></P> +</CENTER><P> +Each green block represents a 4 Kbyte read. Each red block represents a +16Kbyte write.</P> +<DL> + <DT> + <I><TT>avque</TT></I> + <DD> + <P> + The <B><I>stochastic</I></B> <B><I>average</I></B> of the + "queue" length sampled just before each I/O is complete, + where ``queue'' here includes those requests in the queue <B>and</B> + those being serviced by the device controller. Unfortunately the <B><I>stochastic</I></B> + <B><I>average</I></B> of a queue length is not the same as the + more commonly understood <B><I>temporal</I></B> or <B><I>time</I></B> + <B><I>average</I></B> of a queue length. </P> + <P> + In the table below, <B>R</B> is the contribution to the sum of the + response times, <B>Qs</B> is the contribution to the sum of the + queue length used to compute the <B><I>stochastic</I></B> average + and <B>Qt</B> is the contribution to the sum of the queue length + × time used to compute the <B><I>temporal</I></B> average. </P> +</DL> + <CENTER> + <TABLE BORDER="1"> + <TR> + <TH ALIGN="CENTER"> + <B>Time</B><BR> + (msec)</TH> + <TH ALIGN="CENTER"><B>Event</B></TH> + <TH ALIGN="CENTER"><B>R</B><BR> + (msec)</TH> + <TH ALIGN="CENTER"><B>Qs</B></TH> + <TH ALIGN="CENTER"><B>Qt</B><BR> + (msec)</TH> + </TR> + <TR> + <TD ALIGN="RIGHT">300</TD> + <TD>Start I/O #1 (write)</TD> + <TD ALIGN="RIGHT"> </TD> + <TD ALIGN="RIGHT"> </TD> + <TD ALIGN="RIGHT"> </TD> + </TR> + <TR> + <TD ALIGN="RIGHT">320</TD> + <TD>End I/O #1</TD> + <TD ALIGN="RIGHT">20</TD> + <TD ALIGN="RIGHT">1</TD> + <TD ALIGN="RIGHT">1×20</TD> + </TR> + <TR> + <TD ALIGN="RIGHT">320</TD> + <TD>Start I/O #2 (read)</TD> + <TD ALIGN="RIGHT"> </TD> + <TD ALIGN="RIGHT"> </TD> + <TD ALIGN="RIGHT"> </TD> + </TR> + <TR> + <TD ALIGN="RIGHT">320</TD> + <TD>Start I/O #3 (read)</TD> + <TD ALIGN="RIGHT"> </TD> + <TD ALIGN="RIGHT"> </TD> + <TD ALIGN="RIGHT"> </TD> + </TR> + <TR> + <TD ALIGN="RIGHT">330</TD> + <TD>End I/O #2</TD> + <TD ALIGN="RIGHT">10</TD> + <TD ALIGN="RIGHT">2</TD> + <TD ALIGN="RIGHT">2×10</TD> + </TR> + <TR> + <TD ALIGN="RIGHT">340</TD> + <TD>End I/O #3</TD> + <TD ALIGN="RIGHT">20</TD> + <TD ALIGN="RIGHT">1</TD> + <TD ALIGN="RIGHT">1×10</TD> + </TR> + <TR> + <TD ALIGN="RIGHT">360</TD> + <TD>Start I/O #4 (write)</TD> + <TD ALIGN="RIGHT"> </TD> + <TD ALIGN="RIGHT"> </TD> + <TD ALIGN="RIGHT"> </TD> + </TR> + <TR> + <TD ALIGN="RIGHT">360</TD> + <TD>Start I/O #5 (read)</TD> + <TD ALIGN="RIGHT"> </TD> + <TD ALIGN="RIGHT"> </TD> + <TD ALIGN="RIGHT"> </TD> + </TR> + <TR> + <TD ALIGN="RIGHT">360</TD> + <TD>Start I/O #6 (read)</TD> + <TD ALIGN="RIGHT"> </TD> + <TD ALIGN="RIGHT"> </TD> + <TD ALIGN="RIGHT"> </TD> + </TR> + <TR> + <TD ALIGN="RIGHT">370</TD> + <TD>End I/O #6</TD> + <TD ALIGN="RIGHT">10</TD> + <TD ALIGN="RIGHT">3</TD> + <TD ALIGN="RIGHT">3×10</TD> + </TR> + <TR> + <TD ALIGN="RIGHT">380</TD> + <TD>End I/O #5</TD> + <TD ALIGN="RIGHT">20</TD> + <TD ALIGN="RIGHT">2</TD> + <TD ALIGN="RIGHT">2×10</TD> + </TR> + <TR> + <TD ALIGN="RIGHT">400</TD> + <TD>End I/O #4</TD> + <TD ALIGN="RIGHT">40</TD> + <TD ALIGN="RIGHT">1</TD> + <TD ALIGN="RIGHT">1×20</TD> + </TR> +</TABLE> +</CENTER> +<DL> + <DT> + + <DD> + <P> + The (stochastic) average response time is sum(<B>R</B>) / 6 = 120 / + 6 = 20 msec.</P> + <P> + The <B><I>stochastic</I></B> <B><I>average</I></B> of the queue + length is sum(<B>Qs</B>) / 6 = 10 / 6 = 1.67.</P> + <P> + The <B><I>temporal </I></B> <B><I>average</I></B> of the queue + length is sum(<B>Qt</B>) / 100 = 120 / 100 = 1.20.</P> + <P> + Even in this simple example, the two methods for computing the "average" + queue length produce different answers. As the inter-arrival rate + for I/O requests becomes more variable, and particularly when many I/O + requests are issued in a short period of time followed by a period of + quiescence, the two methods produce radically different results.</P> + <P> + For example if the idle period in the example above was 420 msec rather + than 20 msec, then the <B><I>stochastic</I></B> <B><I>average</I></B> + would remain unchanged at 1.67, but the <B><I>temporal average</I></B> + would fall to 120/500 = 0.24 ... given that this disk is now <B>idle</B> + for 420/500 = 84% of the time one can see how misleading the <B><I>stochastic</I></B> + <B><I>average</I></B> can be. Unfortunately many disks are subject + to exactly this pattern of short bursts when many I/Os are enqueued, + followed by long periods of comparative calm (consider flushing dirty + blocks by <I>bdflush</I> in IRIX or the DBWR process in Oracle). + Under these circumstances, <I><TT>avque</TT> </I>as reported by <I>sar</I> + can be very misleading.</P> + <DT> + <I><TT>avserv</TT></I> + <DD> + <P> + Because multiple operations may be processed by the controller at the + same time, and the order of completion is not necessarily the same as + the order of dispatch, the notion of individual service time is + difficult (if not impossible) to measure. Rather, <I>sar</I> + approximates using the total time the disk was busy processing at + least one request divided by the number of completed requests.</P> + <P> + In the example above this translates to busy for 80 msec, in which time + 6 I/Os were completed, so the average service time is 13.33 msec.</P> + <DT> + <I><TT>avwait</TT></I> + <DD> + <P> + For reasons similar to those applying to <I><TT>avserv</TT></I> the + average time spent waiting cannot be split between waiting in the + queue of requests to be sent to the controller and waiting at the + controller while some other concurrent request is being processed. So <I>sar</I> + computes the total time spent waiting as the total response time minus + the total service time, and then averages over the number of completed + requests.</P> + <P> + In the example above this translates to a total waiting time of 120 + msec - 80 msec, in which time 6 I/Os were completed, so the average + waiting time is 6.67 msec.</P> +</DL> +<P> +When run with a <B>-d</B> option, <I>sar</I> reports the following for +each disk spindle:</P> +<TABLE BORDER="1"> + <CAPTION ALIGN="BOTTOM"><B>Table 3: PCP and sar metric equivalents</B></CAPTION> + <TR VALIGN="TOP"> + <TH>Metric</TH> + <TH>Units</TH> + <TH>PCP equivalent<BR> + (in terms of the rate converted metrics in Table 2)</TH> + </TR> + <TR VALIGN="TOP"> + <TD><I><TT>%busy</TT></I></TD> + <TD>percent</TD> + <TD>100 * <I><TT>disk.dev.active</TT></I> </TD> + </TR> + <TR VALIGN="TOP"> + <TD><I><TT>avque</TT></I></TD> + <TD>I/O operations</TD> + <TD>N/A (see above)</TD> + </TR> + <TR VALIGN="TOP"> + <TD><I><TT>r+w/s</TT></I></TD> + <TD>I/Os per second</TD> + <TD><I><TT>disk.dev.total</TT></I></TD> + </TR> + <TR VALIGN="TOP"> + <TD><I><TT>blks/s</TT></I></TD> + <TD>512-byte blocks per second</TD> + <TD><I><TT>disk.dev.blktotal</TT></I></TD> + </TR> + <TR VALIGN="TOP"> + <TD><I><TT>w/s</TT></I></TD> + <TD><B>write</B> I/Os per second</TD> + <TD><I><TT>disk.dev.write</TT></I></TD> + </TR> + <TR VALIGN="TOP"> + <TD><I><TT>wblks/s</TT></I></TD> + <TD>512-byte blocks <B>written</B> per second</TD> + <TD><I><TT>disk.dev.blkwrite</TT></I></TD> + </TR> + <TR VALIGN="TOP"> + <TD><I><TT>avwait</TT></I></TD> + <TD>milliseconds</TD> + <TD>1000 * (<I><TT>disk.dev.response</TT></I> <I><TT>- + disk.dev.active)</TT></I> / <I><TT>disk.dev.total</TT></I></TD> + </TR> + <TR VALIGN="TOP"> + <TD><I><TT>avserv</TT></I></TD> + <TD>milliseconds</TD> + <TD>1000 * <I><TT>disk.dev.active</TT></I> / <I><TT>disk.dev.total</TT></I></TD> + </TR> +</TABLE> +<P> +The table below shows how the PCP tools and <I>sar</I> would report the +disk performance over the 100 millisecond interval from the example +above:</P> +<TABLE BORDER="1"> + <CAPTION ALIGN="BOTTOM"><B>Table 3: Illustrative values and + calculations</B></CAPTION> + <TR> + <TH>Rate converted PCP metric<BR> + (like in Table 2)</TH> + <TH>sar metrics</TH> + <TH>Explanation</TH> + </TR> + <TR> + <TD><I><TT>disk.dev.read</TT></I></TD> + <TD>N/A</TD> + <TD>4 reads in 100 msec = 40 reads per second</TD> + </TR> + <TR> + <TD><I><TT>disk.dev.write</TT></I></TD> + <TD><I><TT>w/s</TT></I></TD> + <TD>2 writes in 100 msec = 20 writes per second</TD> + </TR> + <TR> + <TD><I><TT>disk.dev.total</TT></I></TD> + <TD><I><TT>r+w/s</TT></I></TD> + <TD>4 reads + 2 write in 100 msec = 60 I/Os per second</TD> + </TR> + <TR> + <TD><I><TT>disk.dev.blkread</TT></I></TD> + <TD>N/A</TD> + <TD>4 * 4 Kbytes = 32 blocks in 100 msec = 320 blocks read per + second</TD> + </TR> + <TR> + <TD><I><TT>disk.dev.blkwrite</TT></I></TD> + <TD><I><TT>wblks/s</TT></I></TD> + <TD>2 * 16 Kbytes = 64 blocks in 100 msec = 640 blocks written + per second</TD> + </TR> + <TR> + <TD><I><TT>disk.dev.blktotal</TT></I></TD> + <TD><I><TT>blks/s</TT></I></TD> + <TD>96 blocks in 100 msec = 960 blocks per second</TD> + </TR> + <TR> + <TD><I><TT>disk.dev.read_bytes</TT></I></TD> + <TD>N/A</TD> + <TD>4 * 4 Kbytes = 16 Kbytes in 100 msec = 160 Kbytes per second</TD> + </TR> + <TR> + <TD><I><TT>disk.dev.write_bytes</TT></I></TD> + <TD>N/A</TD> + <TD>2 * 16 Kbytes = 32 Kbytes in 100 msec = 320 Kbytes per + second</TD> + </TR> + <TR> + <TD><I><TT>disk.dev.bytes</TT></I></TD> + <TD>N/A</TD> + <TD>48 Kbytes in 100 msec = 480 Kbytes per second</TD> + </TR> + <TR> + <TD><I><TT>disk.dev.active</TT></I></TD> + <TD><I><TT>%busy</TT></I></TD> + <TD>80 msec active in 100 msec = 0.8 or 80%</TD> + </TR> + <TR> + <TD><I><TT>disk.dev.response</TT></I></TD> + <TD>N/A</TD> + <TD>Disregard (see comments in Table 2)</TD> + </TR> + <TR> + <TD>N/A</TD> + <TD><I><TT>avque</TT></I></TD> + <TD>1.67 requests (see derivation above)</TD> + </TR> + <TR> + <TD>N/A</TD> + <TD><I><TT>avwait</TT></I></TD> + <TD>6.67 msec (see derivation above)</TD> + </TR> + <TR> + <TD>N/A</TD> + <TD><I><TT>avserv</TT></I></TD> + <TD>13.33 msec (see derivation above)</TD> + </TR> +</TABLE> +<P> +In practice many of these metrics are of little use. Fortunately the +most common performance problems related to disks can be identified +quite simply as follows:</P> +<DL> + <DT> + <B>Device saturation</B> + <DD> + Occurs when <I><TT>disk.dev.active</TT></I> is close to 1.0 + (which is the same as <I><TT>%busy</TT></I> is close to 100%). + <DT> + <B>Device throughput</B> + <DD> + Use <I><TT>disk.dev.bytes</TT></I> (or <I><TT>blks/s</TT></I> + divided by 2 to produce Kbytes per second) + <DD> + The peak value depends on the bus and disk characteristics, and is + subject to significant variation depending on the distribution, size + and type of requests. Fortunately in many environments the peak value + does not change over time, so once established, monitoring thresholds + tend to remain valid. + <DT> + <B>Read/write mix</B> + <DD> + For some disks (and RAID devices in particular) writes may be slower + than reads. The ratio of <I><TT>disk.dev.write</TT></I> to <I><TT>disk.dev.total</TT></I> + (or <I><TT>w/s</TT></I> to <I><TT>r+w/s</TT></I>) indicates the + fraction of I/O requests that are writes. +</DL> +<P> +In terms of the available instrumentation from the IRIX kernel, one +potentially useful metric would be the stochastic average of the +response time per completed I/O operation, which in the sample above +would be 20 msec. Unfortunately no performance tool reports this +directly.</P> +<UL> + <LI> + For <I>sar</I>, this metric is the sum of <I><TT>avwait</TT></I> + and <I><TT>avserv</TT></I>. + <P> + </P> + <LI> + The common PCP tools only support temporal rate conversion for + counters, however the stochastic average of the response time can be + computed with the PCP inference engine (<I>pmie</I>) using an + expression of the form: + <PRE> +<TT>avg_resp = 1000 * disk.dev.response / disk.dev.total;</TT> +</PRE> +</UL> + +<P><BR></P> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 BGCOLOR="#e2e2e2"> + <TR><TD WIDTH=100% BGCOLOR="#081c59"><P ALIGN=LEFT><FONT SIZE=5 COLOR="#ffffff"><B>A real example</B></FONT></P></TD></TR> +</TABLE> +<P> +Consider this data from<B> sar -d</B> with a <B>10 minute</B> update +interval:</P> +<PRE> + device %busy avque r+w/s blks/s w/s wblks/s avwait avserv + dks0d2 34 12.8 32 988 29 874 123.1 10.5 + dks0d5 34 12.5 33 1006 29 891 119.0 10.4 +</PRE> +<P> +At first impression, queue lengths of 12-13 requests and wait time of +120msec looks pretty bad. </P> +<P> +But further investigation is warranted ...</P> +<UL> + <LI> + most of the I/Os are writes (58 of 65 I/Os per second) + <LI> + average I/Os are (874+891)*512/(29+29) = 15580 bytes ... close to + default 16K filesystem block size + <LI> + to sustain (874+891)*512 = 903680 bytes of write throughput per second + for at least 10 minutes you are doing a lot of file writes + <LI> + the disks are not unduly busy at 34% utilization + <LI> + consider what happens when <I>bdflush</I>, <I>pdflush</I> and + friends run ... lets make some simplifying assumptions to make the + arithmetic easy + <UL> + <LI> + we are dirtying (writing) 60 x 16 Kbyte pages (983040 bytes) per second + <LI> + flushing goes off every 10 seconds, but the page cache is scanned in + something under 10 msec + <LI> + to keep up, each flush must push out 600 pages + <LI> + I/O is balanced across 2 disks + <LI> + disk service time is 10 msec per I/O + <LI> + after the flushing code has scanned the page cache, all 300 writes per + disk are on the queue <B>before</B> the first one is done (this + is what skews the wait time and queue lengths) + </UL> + <LI> + disk utilization is 300 * 10 / (10 * 1000) = 0.3 = 30% + <LI> + the stochastic average wait time is (0 + 10 + 20 + ... + 2990) / 300 + > = 150 msec + <LI> + time to empty the queue after a flush is 3 seconds + <LI> + the temporal average queue length is 0 * 7/10 + 150 * 3/10 = 45 +</UL> +<P> +The complicating issue here is that the I/O demand is very bursty and +this is what skews the "average" measures.</P> +<P> +In this case, the I/O is probably <B>asynchronous</B> with respect to +the process(es) doing the writing. Under these circumstances, +performance is unlikely to improve dramatically if the aggregate I/O +bandwidth was increased (e.g. by spreading the writes across more disk +spindles).</P> +<P> +However if the I/O is <B>synchronous</B> (e.g. it it was read dominated, +or the I/O was to a raw disk), then more I/O would reduce application +running time.</P> +<P> +There are also <B>hybrid</B> scenarios in which a small number of +synchronous reads are seriously slowed down during the bursts of +asynchronous writes. In the example above, a read could have the +misfortune of being queued behind 300 writes (or delayed for 3 seconds).</P> + +<P><BR></P> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 BGCOLOR="#e2e2e2"> + <TR><TD WIDTH=100% BGCOLOR="#081c59"><P ALIGN=LEFT><FONT SIZE=5 COLOR="#ffffff"><B>Beware of Wait I/O</B></FONT></P></TD></TR> +</TABLE> +<P> +PCP (and <I>sar</I> and <I>osview</I> and ...) all report CPU +utilization broken down into:</P> +<UL> + <LI> + user + <LI> + system (sys, intr) + <LI> + idle + <LI> + wait (for file system I/O, graphics, physical I/O and swap I/O) +</UL> +<P> +Because I/O does not "belong" to any processor (and in some +cases may not "belong" to any current process), a CPU that is +"waiting for I/O" is more accurately described as an +"idle CPU while at least one I/O is outstanding".</P> +<P> +Anomalous Wait I/O time occurs under light load when a small number of <B>processes</B> +are waiting for I/O but many <B>CPUs</B> are otherwise idle, but +appear in the "Wait for I/O" state. When the number of CPUs +increases to 30, 60 or 120 then 1 process doing I/O can make all of the +CPUs except 1 look like they are all waiting for I/O, but clearly no +amount of I/O bandwidth increase is going to make any difference to +these CPUs. And if that one process is doing asynchronous I/O and not +blocking, then additional I/O bandwidth will not make it run faster +either.</P> + +<TABLE WIDTH=100% BORDER=0 CELLPADDING=10 CELLSPACING=20> + <TR><TD BGCOLOR="#e2e2e2" WIDTH=70%><BR><IMG SRC="images/stepfwd_on.png" WIDTH=16 HEIGHT=16 BORDER=0> Using <I>pmchart</I> to display concurrent disk and CPU activity (aggregated over all CPUs and all disks respectively).<BR> +<PRE><B> +$ source /etc/pcp.conf +$ tar xzf $PCP_DEMOS_DIR/tutorials/diskperf.tgz +$ pmchart -t 2sec -O -0sec -a diskperf/waitio -c diskperf/waitio.view +</B></PRE> +<P>The system has 4 CPUs, several disks and only 1 process really doing I/O.</P> +<P>Note that over time:</P> +<UL> + <LI> + in the top chart as the CPU user (blue) and system (red) time + increases, the Wait I/O (pale blue) time decreases + <LI> + from the bottom chart, the I/O rate is pretty constant throughout + <LI> + in the bursts where the I/O rate falls, the Wait I/O time becomes CPU + idle (green) time +</UL> +</TD></TR> +</TABLE> + +<P><BR></P> +<HR> +<CENTER> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0> + <TR> <TD WIDTH=50%><P>Copyright © 2007-2010 <A HREF="http://www.aconex.com/"><FONT COLOR="#000060">Aconex</FONT></A><BR>Copyright © 2000-2004 <A HREF="http://www.sgi.com/"><FONT COLOR="#000060">Silicon Graphics Inc</FONT></P></TD> + <TD WIDTH=50%><P ALIGN=RIGHT><A HREF="http://pcp.io/"><FONT COLOR="#000060">PCP Site</FONT></A><BR>Copyright © 2012-2014 <A HREF="http://www.redhat.com/"><FONT COLOR="#000060">Red Hat</FONT></P></TD> </TR> +</TABLE> +</CENTER> +</BODY> +</HTML> diff --git a/man/html/howto.enterprise.html b/man/html/howto.enterprise.html new file mode 100644 index 0000000..c50a354 --- /dev/null +++ b/man/html/howto.enterprise.html @@ -0,0 +1,464 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> +<!-- + (c) Copyright 2000-2004 Silicon Graphics Inc. All rights reserved. + 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 + http://creativecommons.org/licenses/by-sa/3.0/us/ . +--> +<HTML> +<HEAD> + <meta http-equiv="content-type" content="text/html; charset=utf-8"> + <meta http-equiv="content-style-type" content="text/css"> + <link href="pcpdoc.css" rel="stylesheet" type="text/css"> + <link href="images/pcp.ico" rel="icon" type="image/ico"> + <TITLE>Integrating PCP into an Enterprise Management Strategy</TITLE> +</HEAD> +<BODY LANG="en-AU" TEXT="#000060" DIR="LTR"> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 STYLE="page-break-before: always"> + <TR> <TD WIDTH=64 HEIGHT=64><FONT COLOR="#000080"><A HREF="http://pcp.io/"><IMG SRC="images/pcpicon.png" NAME="pmcharticon" ALIGN=TOP WIDTH=64 HEIGHT=64 BORDER=0></A></FONT></TD> + <TD WIDTH=1><P> </P></TD> + <TD WIDTH=500><P VALIGN=MIDDLE ALIGN=LEFT><A HREF="index.html"><FONT COLOR="#cc0000">Home</FONT></A> · <A HREF="lab.pmchart.html"><FONT COLOR="#cc0000">Charts</FONT></A> · <A HREF="timecontrol.html"><FONT COLOR="#cc0000">Time Control</FONT></A></P></TD> + </TR> +</TABLE> +<H1 ALIGN=CENTER STYLE="margin-top: 0.48cm; margin-bottom: 0.32cm"><FONT SIZE=7>Integrating PCP into an Enterprise Management Strategy</FONT></H1> +<TABLE WIDTH=15% BORDER=0 CELLPADDING=5 CELLSPACING=10 ALIGN=RIGHT> + <TR><TD BGCOLOR="#e2e2e2"><IMG SRC="images/system-search.png" WIDTH=16 HEIGHT=16 BORDER=0> <I>Tools</I><BR><PRE> +pmie +pmieconf +pmlogger +pmlogconf +</PRE></TD></TR> +</TABLE> +<P> +This chapter of the Performance Co-Pilot tutorial discusses the steps +required to integrate PCP into the various management frameworks available. +It takes into consideration the distributed nature of both the management +frameworks and of the PCP tools, and how best to combine the functionality +they offer.</P> +<P> +For an explanation of Performance Co-Pilot terms and acronyms, consult +the <A HREF="glossary.html">PCP glossary</A>.</P> + +<P><BR></P> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 BGCOLOR="#e2e2e2"> + <TR><TD WIDTH=100% BGCOLOR="#081c59"><P ALIGN=LEFT><FONT SIZE=5 COLOR="#ffffff"><B>Points of Integration</B></FONT></P></TD></TR> +</TABLE> +<P> +Following is a brief description on how PCP can be integrated in terms of +some of the aligned features of PCP and the typical management framework. +<H4>Data</H4> +<P> +The PCP archive logging utility <b>pmlogger</b>(1) +generates performance data files in the PCP archive format, +which is specifically designed for optimal fetch latency +when retrieving data from the archive for replay and when seeking to +random time points in the archive. +This format is specific to the PCP tools and the PMAPI, and clearly +external interfaces are necessary for non-PCP tools to read the data. +<P> +The <b>LOGIMPORT</b>(3) APIs provide a mechanism for +importing data into a PCP archive. Using these services, tools +are provided to import common sources of performance data such as +spreadsheets, binary data from <b>sar</b>(1) and <b>iostat</b>(1) output. +Other tools can easily be developed in C or Perl, see <b>LOGIMPORT</b>(3), +<b>pmiStart</b>(3) and <b>PCP::LogImport</b>(3). +<P> +There are a number of PCP tools which have specifically been developed with +the aim of producing a format which is easily incorporated into an external +framework, database, or spreadsheet application - for example, the +<b>pmdumptext</b>(1) and <b>pmlogsummary</b>(1) tools both provide options to +output data in a time-stamped, tab-delimited or comma-separated form, which +is easily incorporated into other tools. +PCP also provides daily log rotation, merging and culling facilities for +multiple collector hosts from a single monitor host, as well as the +automated <I>pmchart/cron/pmsnap</I> performance graph image generation +facility. +</P> +<P> +Due to the unlimited potential consumers of this historical performance data, +it is left as an exercise for the reader to figure out how best to incorporate +this data into their own environment. +</P> +<P> +Note that all of the PCP tools are "timezone-aware" and can switch +between the timezone of the monitoring machine and the timezone of the +collector machine for which the archive was generated (this information is +stored in the archive). Also, PCP archives can be generated on a machine +of one operating system version, architecture or byte-order, and replayed +on a completely different machine. +</P> +<H4>Events</H4> +<P> +Among the more compelling reasons for making use of a management framework +to administer an enterprise are the distributed monitoring and centralized +analysis aspects. +All frameworks provide event monitoring facilities, of varying complexity. +Some provide simple point to point event generation, others have proxy event +servers which allow events to be filtered and then potentially passed upstream +to another event monitor. +To allow the framework to be extended, the frameworks will typically provide +a mechanism for external applications to push their own events into the +framework, and it is this feature which we wish to exploit in our PCP +integration efforts. +</P> +<P> +Although PCP does provide a powerful inference engine in <b>pmie</b>(1) (as well +as a far richer set of performance metrics than the more generic frameworks can +provide, and low latency protocols designed specifically for transporting +performance data quickly), no attempt is made to provide an event +"sink" - some application which will display and filter +performance events for the user. +From an enterprise management point of view, an event monitoring +facility specifically for performance events would be exactly the wrong +thing to do from within PCP - system administrators managing a wide array of +different machines should expect to see all system-wide events coming to a +single point for their notification. +</P> +<P> +So, the integration point must be from <b>pmie</b>(1) - when it detects an +abnormal performance situation, it must pass it on in the most appropriate +manner possible. Unfortunately, the various event management frameworks +have widely differing mechanisms for receiving events, so each framework +must be handled separately in order to make best use of their event viewing +and filtering capabilities. +</P> +<CENTER> +<IMG SRC="images/rattle.png" ALIGN="MIDDLE" WIDTH="430" HEIGHT="340"> +</CENTER> +<P> +The diagram shows a typical <b>pmie</b>(1) setup - <B>rattle.melbourne.sgi.com</B> +running <b>pmie</b>, fetching performance data from a variety of sources, then +evaluating its set of performance rules and generating events into whichever +event "sinks" have been specified. +Specifying how to generate an event, which rules to use, how frequently to +evaluate each of the rules, which hosts to monitor, etc, is performed by +the <b>pmieconf</b>(1) utility, which can be extended to allow new frameworks +to be incorporated. +</P> +<H4>User Interface</H4> +<P> +A number of the enterprise management frameworks have the ability to provide +closer integration between the tools themselves, for example starting PCP +tools from a menu option of some of the framework's tools, or by installing +additional on-line help for the performance events which PCP generates. +This level of integration is not attempted, and is not seen as providing +much value in practice. +The <b>pmieconf</b>(1) utility is the definitive +source of help text for the performance events generated by <b>pmie</b>(1) - +it describes the rules and each of the customizable variables affecting +the rules (including the "global" variables affecting all of the +rules, such as where to send events when a performance event is generated). +</P> + +<P><BR></P> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 BGCOLOR="#e2e2e2"> + <TR><TD WIDTH=100% BGCOLOR="#081c59"><P ALIGN=LEFT><FONT SIZE=5 COLOR="#ffffff"><B>CA/Unicenter TNG (Computer Associates)</B></FONT></P></TD></TR> +</TABLE> +<P> +<B>Step-by-step</B> - how to setup and ensure <b>pmie</b>(1) can talk to the +Unicenter TNG Framework: +</P> +<UL> +<LI> +Start CCI services on the monitor node, i.e. the node where <b>pmie</b> +events should be propagated to (a Windows machine - "hugh" - in +this example). +For a Windows monitoring node, refer to the "Services" window +from the "Control Panel". +</P> +<LI> +Start CCI services on the monitored node, i.e. the node where <b>pmie</b> +is running (an IRIX machine - "wobbly" - in this example). +<PRE> +wobbly# $CAIGLBL0000/bin/unicntrl start cci +wobbly# +</PRE> +</P> +<LI> +Ensure the connection between the two nodes is active. For UNIX machines: +<PRE> +wobbly# $CAIGLBL0000/cci/bin/rmt status + + Sysid State Last Send Time Last Receive Time +--------|---------------------|---------------|----------------- +hugh ACTIVE 041099 17:54:37 041199 13:42:01 + +wobbly# +</PRE> +For Windows machines: +<PRE> +C:\TNGFW\BIN>rmtcntrl status +SUCCESS: information returned +Sysid State Last Send Time Last Receive time +--------|---------------------|---------------|----------------- +HUGH ACTIVE +WOBBLY ACTIVE Apr-10-99 17:58:25 Apr-10-99 17:58:25 + +C:\TNGFW\BIN> +</PRE> +</P> +<LI> +Send a test event to the monitoring node from the node where <b>pmie</b> +will be running +<PRE> +wobbly# $CAIGLBL0000/bin/cawto -n hugh -g Performance -s wobbly test event +</PRE> +</P> +<LI> +To verify that the event is successfully received on a Windows NT monitoring +host, use the Event Console, which lists events as they arrive. +</P> +<P>There are several tools which ship with the TNG Framework for examining +and verifying the connection between two nodes - such as <b>oprping</b>(1) - +refer to the Unicenter TNG documentation for full details. +<LI> +Once the test event propagates successfully, enable <b>pmie</b> event generation +into the TNG Framework: +<PRE> +wobbly# pmieconf modify global tngfw_action yes +wobbly# /etc/init.d/pmie start +</PRE> +</UL> +<B>Configuration options</B> - how to customize the setup for different +environments: +<UL> +<LI> +The node to which events are sent is identified by the tngfw_node +<b>pmieconf</b> variable, so to setup event propagation from <b>pmie</b> +on rattle to TNG on hugh as described above: +<PRE> +wobbly# pmieconf modify global tngfw_node hugh +wobbly# /etc/init.d/pmie start +</PRE> +<LI> +Other parameters associated with TNG events can also be specified - these +include the color and category of each individual event, a group of events, +or globally for all events: +<PRE> +wobbly# pmieconf modify global tngfw_color Yellow +wobbly# pmieconf modify global tngfw_category "PMIE Events" +wobbly# pmieconf modify cisco tngfw_color Red +wobbly# /etc/init.d/pmie start +</PRE> +</UL> +</P> +<CENTER> +<IMG SRC="images/tngconsole.png" ALIGN="MIDDLE" WIDTH="699" HEIGHT="444"> +</CENTER> + +<P><BR></P> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 BGCOLOR="#e2e2e2"> + <TR><TD WIDTH=100% BGCOLOR="#081c59"><P ALIGN=LEFT><FONT SIZE=5 COLOR="#ffffff"><B>HP OpenView (Hewlett-Packard)</B></FONT></P></TD></TR> +</TABLE> +<P> +<B>Step-by-step</B> on how to setup and ensure <b>pmie</b>(1) can talk to OpenView: +</P> +<UL> +<LI> +Start the <b>pmcd</b>(1) daemon on the node which will receive <b>pmie</b>(1) +events - "wobbly" in this example. +<PRE> +wobbly# /etc/init.d/snmp start +wobbly# /etc/init.d/ovnnm start +</PRE> +</P> +<LI> +Send a test event to the monitoring node from the node where <b>pmie</b>(1) +will be running (OV_BIN is typically /usr/OV/bin): +<PRE> +rattle# cd $OV_BIN +rattle# ./ovevent -c "Status Events" -s Normal \ +.1.3.6.1.4.1.11.2.17.1.0.58916872 \ +.1.3.6.1.4.1.11.2.17.2.1.0 Integer 14 \ +.1.3.6.1.4.1.11.2.17.2.2.0 OctetString "rattle" \ +.1.3.6.1.4.1.11.2.17.2.4.0 OctetString "test event" +</PRE> +<LI> +To verify that the event is successfully received, run the OpenView event +monitoring program (pictured here): +<PRE> +wobbly# cd $OV_BIN +wobbly# ./xnmevents & +</PRE> +<LI> +If this event propagates successfully, enable <b>pmie</b> event generation +into OpenView: +<PRE> +rattle# pmieconf modify global ov_action yes +rattle# /etc/init.d/pmie start +</PRE> +</UL> +<P> +<CENTER> +<IMG SRC="images/xnmevents.png" ALIGN="RIGHT" WIDTH="247" HEIGHT="210"> +</CENTER> +The <b>xnmevents</b>(1) GUI connects to the <b>pmcd</b>(1) daemon on the monitoring +node which supplies any new events which arrive while <b>xnmevents</b> is +running. +</P> +The image to the right shows the <b>xnmevents</b> main window. +On receipt of a new <b>pmie</b> event, the "Threshold Events" +toggle button changes +color according to the event severity, indicating that there are new events +- clicking on the toggle button brings up the viewer window (shown below). +</P> +<P> +The viewer lets you view, filter, and +acknowledge events (once all events are acknowledged, the "Threshold +Events" button becomes white - until the next event arrives). +</P> +<B>Configuration options</B> - using <b>pmieconf</b>(1) to customize the setup +for different environments: +<UL> +<LI> +The node to which events are sent is identified by the ov_node <b>pmieconf</b> +variable, so to setup event transferral from rattle to wobbly as described +above, I ran: +<PRE> +# pmieconf modify global ov_node wobbly +# /etc/init.d/pmie start +</PRE> +<LI> +Other parameters associated with OpenView events can also be specified - these +include the category and severity of each individual event, a group +of events, or globally for all events: +<PRE> +rattle# pmieconf modify filesys.filling ov_severity Critical +rattle# pmieconf modify filesys.filling ov_category "Status Events" +rattle# pmieconf modify cisco ov_severity Major +rattle# /etc/init.d/pmie start +</PRE> +</UL> +<CENTER> +<IMG SRC="images/ovevents.png" ALIGN="MIDDLE" WIDTH="697" HEIGHT="373"> +</CENTER> + +<P><BR></P> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 BGCOLOR="#e2e2e2"> + <TR><TD WIDTH=100% BGCOLOR="#081c59"><P ALIGN=LEFT><FONT SIZE=5 COLOR="#ffffff"><B>EnlightenDSM (Enlighten Software Solutions)</B></FONT></P></TD></TR> +</TABLE> +<P> +<B>Step-by-step</B> on how to setup and ensure <b>pmie</b>(1) can talk to +EnlightenDSM: +</P> +<UL> +<LI> +Start the <b>EnlightenDSM</b>(1) daemons on the host being monitored by +<b>pmie</b>(1) - "wobbly" in this example. +<PRE> +wobbly# /opt/enlighten/bin/start_enl_daemons -r +... +start_emdd: Invoking /opt/emd/bin/emdd... +start_enl_daemons: Invoking /opt/enlighten/bin/pep... +start_enl_daemons: Invoking /opt/enlighten/bin/renld... +start_enl_daemons: Invoking /opt/enlighten/bin/AgentMon... +</PRE> +</P> +<LI> +Start up the Enlighten GUI to verify that events can be received. +Go into the "Events" -> "Status Map" window: +<PRE> +wobbly# /opt/enlighten/bin/xenln & +</PRE> +<LI> +Send a test event to the Enlighten GUI, and verify that the scrolling event +list at the bottom of the "Status Map" window updates after the event has +been sent: +<PRE> +wobbly# /opt/enlighten/bin/EventsCli -n Test -u tps -v 12345 -s 5 -q +</PRE> +<LI> +If this event propagates successfully, enable pmie event generation into Enlighten: +<PRE> +wobbly# pmieconf modify global enln_action yes +wobbly# /etc/init.d/pmie start +</PRE> +</UL> + +<B>Configuration options</B> - using <b>pmieconf</b>(1) to customize the setup: +<P> +The only configurable option of note for Enlighten DSM is the ability +to change the severity setting for individual events, event groups, or +globally for all events (where severity is a number between a low of 1 and +a high of 5, and the default severity value for <b>pmie</b>(1) events is 2): +<PRE> +wobbly# pmieconf modify filesys.filling enln_severity 4 +wobbly# pmieconf modify cisco enln_severity 5 +wobbly# /etc/init.d/pmie start +</PRE> +<P> +<CENTER> +<IMG SRC="images/xenln.png" ALIGN="MIDDLE" WIDTH="581" HEIGHT="505"> +</CENTER> + +<P><BR></P> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 BGCOLOR="#e2e2e2"> + <TR><TD WIDTH=100% BGCOLOR="#081c59"><P ALIGN=LEFT><FONT SIZE=5 COLOR="#ffffff"><B>Extending</A> to Other Frameworks</B></FONT></P></TD></TR> +</TABLE> +<P> +All of the enterprise management frameworks we've come across provide some +mechanism for generating events from outside the framework. +This is usually in the form of a stand-alone utility, but could also be an +API, which packages the attributes associated with an event (these attributes +are usually things like severity, source host, message text, etc) and sends +this to the monitoring host. +</P> +<P> +Since <b>pmie</b>(1) supports running an arbitrary command upon detection of +a performance event (in addition to its other native actions, such as writing +an entry in the system log file), this is the hook we'll use to add support for +additional frameworks. +</P> +<P> +Steps involved when integrating other frameworks with PCP: +</P> +<UL> + <LI> + find or create a utility to generate events into the framework; + <LI> + familiarize yourself with the command line options for this utility, + and decide which options are of interest from a performance-event + perspective; + <LI> + test the utility by hand - ensure that you can run the utility from + the command line and that the framework's monitoring software + successfully receives the event; + <LI> + using the files in <TT>/var/pcp/config/pmieconf/global</TT> as a + guide, create a <b>pmieconf</b>(1) file containing "global" + variables for use in <b>pmieconf</b> - one of these is always an + "action" variable, which allows the framework utility to + be run when <b>pmie</b>(1) generates an event; + <LI> + using <b>pmieconf</b>, ensure that the syntax of your created file + is correct, and that the new variables are visible in the + "global" group; +<PRE> + # pmieconf -r newfile list global +</PRE> + <LI> + finally, install the new file into the + <TT>/var/pcp/config/pmieconf/global</TT> subdirectory + and switch on your new framework action for all of the rules; +<PRE> + # pmieconf modify global new_action yes + # /etc/init.d/pmie start +</PRE> +</UL> +<P>If the framework is sufficiently common that other people may wish +to use your new <b>pmieconf</b>(1) "action", feel free to +<A HREF="contacts.html">share it</A> and we'll incorporate it into +future PCP release.</P> + +<P><BR></P> +<HR> +<CENTER> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0> + <TR> <TD WIDTH=50%><P>Copyright © 2007-2010 <A HREF="http://www.aconex.com/"><FONT COLOR="#000060">Aconex</FONT></A><BR>Copyright © 2000-2004 <A HREF="http://www.sgi.com/"><FONT COLOR="#000060">Silicon Graphics Inc</FONT></P></TD> + <TD WIDTH=50%><P ALIGN=RIGHT><A HREF="http://pcp.io/"><FONT COLOR="#000060">PCP Site</FONT></A><BR>Copyright © 2012-2014 <A HREF="http://www.redhat.com/"><FONT COLOR="#000060">Red Hat</FONT></P></TD> </TR> +</TABLE> +</CENTER> +</BODY> +</HTML> diff --git a/man/html/howto.systemlog.html b/man/html/howto.systemlog.html new file mode 100644 index 0000000..4bca24d --- /dev/null +++ b/man/html/howto.systemlog.html @@ -0,0 +1,500 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> +<HTML> +<HEAD> + <meta http-equiv="content-type" content="text/html; charset=utf-8"> + <meta http-equiv="content-style-type" content="text/css"> + <link href="pcpdoc.css" rel="stylesheet" type="text/css"> + <link href="images/pcp.ico" rel="icon" type="image/ico"> + <TITLE>System Event Log Instrumentation</TITLE> +</HEAD> +<BODY LANG="en-AU" TEXT="#000060" DIR="LTR"> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 STYLE="page-break-before: always"> + <TR> <TD WIDTH=64 HEIGHT=64><FONT COLOR="#000080"><A HREF="http://pcp.io/"><IMG SRC="images/pcpicon.png" NAME="pmcharticon" ALIGN=TOP WIDTH=64 HEIGHT=64 BORDER=0></A></FONT></TD> + <TD WIDTH=1><P> </P></TD> + <TD WIDTH=500><P VALIGN=MIDDLE ALIGN=LEFT><A HREF="index.html"><FONT COLOR="#cc0000">Home</FONT></A> · <A HREF="lab.pmchart.html"><FONT COLOR="#cc0000">Charts</FONT></A> · <A HREF="timecontrol.html"><FONT COLOR="#cc0000">Time Control</FONT></A></P></TD> + </TR> +</TABLE> +<H1 ALIGN=CENTER STYLE="margin-top: 0.48cm; margin-bottom: 0.32cm"><FONT SIZE=7>System Event Log Instrumentation</FONT></H1> +<TABLE WIDTH=15% BORDER=0 CELLPADDING=5 CELLSPACING=10 ALIGN=RIGHT> + <TR><TD BGCOLOR="#e2e2e2"><IMG SRC="images/system-search.png" WIDTH=16 HEIGHT=16 BORDER=0> <I>Tools</I><BR><PRE> +pmval +pmevent +pmchart +pmdalogger +pmdarsyslog +pmdaelasticsearch +</PRE></TD></TR> +</TABLE> +<P>Capturing system event log information from a collection of geographically +distributed systems in a reliable and useful way presents many challenges. +In order for operations and engineering triage teams to be able to filter +important events from this huge amount of information, events need to be +shipped to a central location, reliably, where they can be indexed and +searched.</P> +<P>Ideally this is done in a way that is both timely and removed +from the systems under observation. Being timely allows events relevant +to an active production problem are available to triage personnel. Being +removed from the production system allows for a reduction of impact to the +observed system, and also allows for collation of events from cooperating +systems (separate databases, application servers, web servers and storage +servers, for example).</P> +<P>In addition to the events logged by the operating system kernel and the +system daemons, it is also highly desirable to capture application events +as well. For minimal operational maintenance overhead, these should all +be managed by a single, reliable event shipping system for application +logs. +This case study documents the design and deployment of one such system, +and focuses on the performance instrumentation used for monitoring and +problem diagnosis in the event management service itself.</P> +</P> + +<P><BR></P> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 BGCOLOR="#e2e2e2"> + <TR><TD WIDTH=100% BGCOLOR="#081c59"><P ALIGN=LEFT><FONT SIZE=5 COLOR="#ffffff"><B> Technology Choices</B></FONT></P></TD></TR> +</TABLE> +<P>A brief overview of the technologies used, and why they +were selected from the many alternatives available, follows. +As this was likely to become a critical system infrastructure component, +and the organisation had existing operational and engineering expertise +in Linux and Java, open source solutions were generally preferred. +The opportunity to evaluate new technologies was foreseen and affected +some of the choices made.</P> +<P><B>Event capturing and transport</B></P> +<P><A HREF="http://www.rsyslog.com/">rsyslog</A> +is the default system log daemon on the Linux distribution used, and +it provides efficient, reliable end-to-end delivery. +It turned out to be easily instrumented - providing both its own metrics +and mechanisms for extending with metrics specific to our own needs. +<P><B>Index and search functionality</B></P> +<P><A HREF="http://www.elasticsearch.org/">elasticsearch</A> and +<A HREF="http://mobz.github.com/elasticsearch-head/">elasticsearch-head</A> +are used as the mechanisms for indexing event messages as they arrive, and +providing event search functionality.</P> + +<P><BR></P> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 BGCOLOR="#e2e2e2"> + <TR><TD WIDTH=100% BGCOLOR="#081c59"><P ALIGN=LEFT><FONT SIZE=5 COLOR="#ffffff"><B> High-level Design</B></FONT></P></TD></TR> +</TABLE> +<P>The design caters for a fairly typical medium-sized web application +deployment. +Each data centre hosting the application (distributed throughout the +world) contains several racks of equipment dedicated to delivering the +service. +Individual racks are populated with closely cooperating machines, each +generating their own system and application logs. +<P> +<CENTER> +<IMG SRC="images/systemlogs.png" ALIGN="MIDDLE" WIDTH="576" HEIGHT="370"> +</CENTER> +</P> +<P>Initially, all logs are streamed directly to a central machine in the +local deployment (typically, within the same rack). +On those machines where application logs are being generated the logs +are immediately merged into the system log stream using the syslog +networking protocol. +We made use of the syslog "facility" concept, to designate all +application logs to be "local0" facility. +</P> +<P>On average, one instance would typically generate several gigabytes of +application logs each day. +The system log traffic is a tiny fraction of that. +</P> +<P>This separation of application log messages from system log messages +became most useful at the final end point (indexing), since the facility +identifier travels with each message (as does source hostname, timestamp +and priority information). +Since elasticsearch was chosen as the indexing and search technology, +the application was modified (via Log4J configuration) to generate logs +messages in <a href="http://json.org">JSON</a> format. +This allowed the information-rich application logs to maintain a clear +separation of critical information (request ID, user ID, identifiers for +the pages being accessed, and many more application level details), such +that these fields could be separately indexed on the receiving end. +</P> +<P>For the remainder of the operating system and service level messages, +conversion to JSON was performed at the final stage, just prior to being +indexed, with the syslog message being one indexed field. The source host +and event generation timestamp that travelled with the message are also +separately indexed. +</P> + +<P><BR></P> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 BGCOLOR="#e2e2e2"> + <TR><TD WIDTH=100% BGCOLOR="#081c59"><P ALIGN=LEFT><FONT SIZE=5 COLOR="#ffffff"><B> Deployment and Instrumentation: rsyslog</B></FONT></P></TD></TR> +</TABLE> +<P>It was highly desirable to gain insight into many levels of the event +transfer process. +Identifying hosts generating too much traffic, or hosts not generating +any log traffic (misconfiguration) was initially important - so, event +counters, and cumulative byte counts of events generated was required. +It was also important to be able to see these data rates alongside the +network interface data rates, to understand the additional load generated +through live streaming of the event log data. +</P> + +<P><B>Instrumenting <i>rsyslog</i> internals</B></P> +<P>The <I>rsyslog</I> daemon runs on each and every machine involved, so +low overhead is a desirable attribute in any instrumentation added. +Not all of the machines are configured the same though (the event +"forwarders" and event "indexers" differ to the +"leaf" nodes, which form most of the event sources), and +so the configuration of <I>rsyslog</I> required some care. +</P> +<P>We took a two-pronged approach to instrumenting the <I>rsyslog</I> +processes. On inspection, it turned out that there is some existing +instrumentation on the <I>rsyslog</I> internal workings available. +It must be explicitly enabled - both at the source level and at runtime. +To enable the instrumentation in an <I>rsyslog</I> build, the +<TT>--enable-impstats</TT> build configuration flag is needed. +Then, enabling the statistics and exporting them at runtime requires +the following additions to the <I>rsyslog</I> configuration: +<PRE> +	# Provide rsyslog statistics +	$ModLoad impstats +	$PStatsInterval 5 +</PRE> +<P>This instructs <I>rsyslog</I> to load the statistics module, and to +export the current state of its statistics on a 5 second interval. +We can then capture those statistics to an arbitrary output channel, +again using a configuration addition.</P> +</P> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0> +<TR><TD> + <IMG ALIGN=RIGHT SRC="images/systemlog-arrival.png" HEIGHT="506" WIDTH="398" BORDER=0> +</TD> +<TD> + <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=15> + <TR><TD> + <P>We would like to incorporate the <I>rsyslog</I> statistics + (giving insight into arrival rates and queueing behaviour) into our + overall performance management strategy - tracking them alongside all + of our other metrics for comparison, graphing, alarming, etc. This is + acheived by a PMDA - <I>pmdarsyslog</I> - which exports these metrics: +<I><PRE> +	rsyslog.interval +	rsyslog.queues.size +	rsyslog.queues.maxsize +	rsyslog.queues.full +	rsyslog.queues.enqueued +	rsyslog.imuxsock.submitted +	rsyslog.imuxsock.discarded +	rsyslog.imuxsock.numratelimiters +	rsyslog.elasticsearch.connfail +	rsyslog.elasticsearch.submits +	rsyslog.elasticsearch.success +	rsyslog.elasticsearch.failed </PRE></I> + </TD></TR> + <TR><TD> + <TABLE WIDTH=100% BORDER=0 CELLPADDING=10 CELLSPACING=20> + <TR><TD BGCOLOR="#e2e2e2" WIDTH=50%><BR><IMG SRC="images/stepfwd_on.png" WIDTH=16 HEIGHT=16 BORDER=0> Install <I>pmdarsyslog</I>: + <PRE><B># source /etc/pcp.env +# cd $PCP_PMDAS_DIR/rsyslog +# ./Install </B></PRE> + </TD></TR> + </TABLE> + </TD></TR> + </TABLE> +</TD></TR> +</TABLE> +<P>The <I>rsyslog</I> configuration addition to achieve the link up +between <I>rsyslog</I> and <I>pmdarsyslog</I> is:</P> +<PRE> +	# Performance instrumentation +	syslog.info |/var/log/pcp/rsyslog/stats +</PRE> +<P>Note that once enabling this, care must be taken to ensure those stats +values are logged only where we wish. In our case, we did not wish these +to end up in the system log file, nor being included in the set of values +being shipped for indexing. +The configuration entries that achieve this restriction in our scenario +are as follows: +<PRE> +	*.*;local0.none;syslog.!=info /var/log/messages +	*.*;syslog.!=info @@log1;RSYSLOG_ForwardFormat +	$ActionExecOnlyWhenPreviousIsSuspended on +	& @@log2 +	& /var/spool/rsyslog-buffer +	$ActionExecOnlyWhenPreviousIsSuspended off +</PRE> +<P>The <I>syslog.info</I> tag identifies the input channel where the +periodic <I>rsyslog</I> metric values are written. +So, the first line above prevents the <I>rsyslog</I> metric values +(<I>syslog.!=info</I>) from appearing in the local system log file +(<I>/var/log/messages</I>). +In addition, we prevent all local application log messages from going +there ("local0"), which is simply so we don't duplicate work that +the application is already doing itself. +The remaining configuration lines are those responsible for forwarding +local host messages to the central log forwarding server for a rack +(log1), and for failing over to a second log server (log2). +Note how we choose not to forward the <I>syslog.info</I> message class. +</P> +<P>From our findings so far, it is worth keep an eye (<I>pmie</I>) on the +queue fullness and discard counts, as they appear to be handy indicators +that a node might not be be keeping up. +In addition, the interval metric should also be kept under surveilance - +if messages arrive more frequently than the configured interval (five +seconds in our case), then it indicates a node somewhere is forwarding +its instrumentation where it should not be (i.e. a misconfiguration). +</P> + +<P><B>Instrumenting <i>rsyslog</i> output channels</B></P> +<P>We can now extend the high level system log counters by drilling +down to specific output channels. +We use the ability of <I>rsyslog</I> to write to a named pipe once more - +this provides a coordination point between the PCP PMDA and the daemon, +without having to log to disk and deal with issues like filesystem free +space management, log rotation, and so forth. +</P> +<P>We extend our configuration with two more lines, as follows:</P> +<PRE> +	# Performance instrumentation +	syslog.info |/var/log/pcp/rsyslog/stats +	local0.* |/var/log/pcp/logger/applog +	*.*;local0.none;syslog.!=info |/var/log/pcp/logger/syslog +</PRE> +<P>The final two lines are feeding all application and other traffic +into two named pipes (fifos) for processing. These need to exist +before <I>rsyslog</I> starts up, and <I>pmdalogger</I> needs to be +configured (at PMDA install time) to be listening for data on these +files.</P> + +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0> +<TR> +<TD> + <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=15> + <TR><TD> + <P>Once that is done, new metrics are then available that give + insight into the number of events being seen for each class of log, + as well as the total event traffic throughput for each:</P> + <I><PRE> +	logger.perfile.applog.bytes +	logger.perfile.applog.count +	logger.perfile.syslog.bytes +	logger.perfile.syslog.count </PRE></I> + </TD></TR> + <TR><TD> + <TABLE WIDTH=100% BORDER=0 CELLPADDING=10 CELLSPACING=20> + <TR><TD BGCOLOR="#e2e2e2" WIDTH=50%><BR><IMG SRC="images/stepfwd_on.png" WIDTH=16 HEIGHT=16 BORDER=0> Install <I>pmdalogger</I>: + <PRE><B># source /etc/pcp.env +# cd $PCP_PMDAS_DIR/logger +# ./Install </B></PRE> + <P>Follow the prompts and configure two logfile entries for the two + named pipes.</P> +<BR> + </TD></TR> + </TABLE> + </TD></TR> + </TABLE> +</TD> +<TD> + <IMG ALIGN=RIGHT SRC="images/systemlog-throughput.png" HEIGHT="418" WIDTH="370" BORDER=0> +</TD> +</TR> +</TABLE> + +<P><B>Deeper event analysis</B> +<P>Finally, this was an opportunity to begin to evaluate the utility of +recently introduced event tracing functionality in PCP. +The logger PMDA which was separately counting application and system log +traffic also had visibility to all event traffic, and has been used to +inspect log contents (for checking event arrival, and for verifying JSON +validity, etc) in what proved a much more convenient way than snooping +the raw network traffic.</P> +<I><PRE> +		logger.perfile.applog.records +		logger.perfile.syslog.records +</PRE></I> +<P>This was done with the command line utility <I>pmevent</I>, which is the +first and most simple of event tracing tools - but even in this basic +"text dump" form, insight was gained by being able to see the +exact traffic passing through each output stream, and some configuration +problems were diagnosed and resolved through its use. +</P> +<P> +<CENTER> +<IMG SRC="images/systemlog-events.png" ALIGN="MIDDLE" WIDTH="826" HEIGHT="455"> +</CENTER> +</P> + +<P><BR></P> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 BGCOLOR="#e2e2e2"> + <TR><TD WIDTH=100% BGCOLOR="#081c59"><P ALIGN=LEFT><FONT SIZE=5 COLOR="#ffffff"><B> A Quick Aside: Buffer Sizes</B></FONT></P></TD></TR> + <TR><TD BGCOLOR="#e2e2e2" WIDTH=100%> +<BR> +<P>If there is a chance of sending extremely large messages through +<I>rsyslog</I> in your environment, such as JVM stack traces or the +like, we found it necessary to increase the default maximum message +size permitted:</P> +<PRE> +	# Global directives +	$MaxMessageSize 65536 +	$PreserveFQDN on +</PRE> +<P>We also insisted that sending hosts fully qualified domain names are +always used, as some of the (global) hosts would otherwise have ambiguous +hostnames.</P> +<P>Buffer sizes can also become problematic in the named pipe implementation +in the Linux kernel. The default (and until relatively recently, unchangeable) +buffer size is 16 pages, which on the typical 4KiB page size system, gives us +only 64KiB. +Since late 2010, this can now be queried and modified though an fcntl(2), +and system wide limited are imposed (1MiB maximum, for non-root users).</P> +<PRE> +	cat /proc/sys/fs/pipe-max-size +	1048576 +</PRE> +<P>If you're interested in the details of the pipe implementation, refer +to <TT>fs/pipe.c</TT> in the Linux kernel source.</P> +<BR> + +</TD></TR> +</TABLE> +<P><BR></P> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 BGCOLOR="#e2e2e2"> + <TR><TD WIDTH=100% BGCOLOR="#081c59"><P ALIGN=LEFT><FONT SIZE=5 COLOR="#ffffff"><B> Deployment and Instrumentation: elasticsearch</B></FONT></P></TD></TR> +</TABLE> +<P><B>Instrumenting elasticsearch</B> +<P>We come to the final stage of our deployment. +System log messages are now flowing to our central repository at an +alarming rate, now we need an efficient way to index them immediately +as they arrive, and also to allow interactive queries of that indexed +data. +This turns out to have been made easy by the <I>elasticsearch</I> +project, which is a distributed, RESTful, search engine built on top +of Lucene.</P> +<P>A basic setup involves downloading the code, untarring, and running +<I>bin/elasticsearch -f</I>. That's it, with no more configuration than +that we have a working solution which correctly identifies the timestamp +fields as distinct from the other text.</P> +<P>From there we can increase reliability and scalability in a number of +ways with <I>elasticsearch</I>, but that setup will differ for different +deployments and is outside the scope here.</P> +<P>Configuring <I>rsyslog</I> to send messages in the JSON format which +the <I>elasticsearch</I> REST API uses, is a matter of configuring the +appropriate output module. +As was the case with the <I>rsyslog</I> stats module, this must be +explicitly enabled - both at the source level and at runtime. +To enable this functionality in an <I>rsyslog</I> build, the +<TT>--enable-elasticsearch</TT> build configuration flag is needed.</P> +<PRE> +	# +	# Create a searchable index using elasticsearch +	# +	$ModLoad omelasticsearch +	*.=info;*.=notice;*.=warn;\ +		auth,authpriv.none;\ +		cron,daemon.none;\ +		mail,news,syslog.none		:omelasticsearch: +</PRE> +<P>The default template does a good job of transforming the arriving +<I>rsyslog</I> messages (including timestamps, facility, priority, +sending hostname, etc) into JSON. +In our case, the application code sending messages on the "local0" +facility has already prepared messages in a rich JSON format already, +so we just use a basic <I>rsyslog</I> template that effectively passes +any "local0" messages straight through to the keeper.</P> + +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0> +<TR> +<TD> + <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=15> + <TR><TD> + <P>For monitoring of the cluster, another PMDA exists which exports + the statistics that <I>elasticsearch</I> makes available. + This exports information about the individual cluster nodes (if more + than one cluster node is in use) - their JVM memory statistics, + cluster and node status, document indexing rates, etc.</P> + </TD></TR> + <TR><TD> + <TABLE WIDTH=100% BORDER=0 CELLPADDING=10 CELLSPACING=20> + <TR><TD BGCOLOR="#e2e2e2" WIDTH=50%><BR><IMG SRC="images/stepfwd_on.png" WIDTH=16 HEIGHT=16 BORDER=0> Install <I>pmdaelasticsearch</I>: + <PRE><B># source /etc/pcp.env +# cd $PCP_PMDAS_DIR/elasticsearch +# ./Install </B></PRE> +<BR> + </TD></TR> + </TD></TR> + <TR><TD> +<P>And the following metrics become available:</P> +<I><PRE> +elasticsearch.cluster.active_shards +elasticsearch.cluster.relocating_shards +elasticsearch.cluster.timed_out +elasticsearch.cluster.active_primary_shards +elasticsearch.cluster.number_of_nodes +elasticsearch.cluster.number_of_data_nodes +elasticsearch.cluster.cluster_name +elasticsearch.cluster.unassigned_shards +elasticsearch.cluster.initializing_shards +elasticsearch.cluster.status.code +elasticsearch.cluster.status.colour +</PRE></I> + </TD></TR> + </TABLE> + </TD></TR> + </TABLE> +</TD> +<TD> +<I><PRE> +	elasticsearch.nodes.indices.size +	elasticsearch.nodes.cache.field_size +	elasticsearch.nodes.cache.field_evictions +	elasticsearch.nodes.cache.filter_size +	elasticsearch.nodes.cache.filter_evictions +	elasticsearch.nodes.cache.filter_count +	elasticsearch.nodes.merges.total_time +	elasticsearch.nodes.merges.current +	elasticsearch.nodes.merges.total +	elasticsearch.nodes.jvm.vm_version +	elasticsearch.nodes.jvm.version +	elasticsearch.nodes.jvm.vm_name +	elasticsearch.nodes.jvm.pid +	elasticsearch.nodes.jvm.uptime_s +	elasticsearch.nodes.jvm.uptime +	elasticsearch.nodes.jvm.gc.count +	elasticsearch.nodes.jvm.gc.time +	elasticsearch.nodes.jvm.gc.collectors.Copy.time +	elasticsearch.nodes.jvm.gc.collectors.Copy.count +	elasticsearch.nodes.jvm.gc.collectors.ParNew.count +	elasticsearch.nodes.jvm.gc.collectors.ParNew.time +	elasticsearch.nodes.jvm.gc.collectors.CMS.count +	elasticsearch.nodes.jvm.gc.collectors.CMS.time +	elasticsearch.nodes.jvm.threads.count +	elasticsearch.nodes.jvm.threads.peak_count +	elasticsearch.nodes.jvm.mem.heap_max +	elasticsearch.nodes.jvm.mem.heap_committed +	elasticsearch.nodes.jvm.mem.non_heap_init +	elasticsearch.nodes.jvm.mem.heap_init +	elasticsearch.nodes.jvm.mem.non_heap_committed +	elasticsearch.nodes.jvm.mem.non_heap_used +	elasticsearch.nodes.jvm.mem.non_heap_max +	elasticsearch.nodes.jvm.mem.heap_used +	elasticsearch.nodes.docs.count +	elasticsearch.nodes.docs.num_docs +</PRE></I> +</TD> +</TR> +</TABLE> + +<P><B>Search queries</B> +<P>Now that data is being indexed in <I>elasticsearch</I>, we can make +interactive queries using <I>elasticsearch-head</I>, which looks a bit +like this:</P> + +<P> +<CENTER> +<IMG SRC="images/elasticsearch.png" ALIGN="MIDDLE" WIDTH="1356" HEIGHT="490"> +</CENTER> +</P> + +<P><BR></P> +<HR> +<CENTER> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0> + <TR> <TD WIDTH=50%><P>Copyright © 2007-2010 <A HREF="http://www.aconex.com/"><FONT COLOR="#000060">Aconex</FONT></A><BR>Copyright © 2000-2004 <A HREF="http://www.sgi.com/"><FONT COLOR="#000060">Silicon Graphics Inc</FONT></P></TD> + <TD WIDTH=50%><P ALIGN=RIGHT><A HREF="http://pcp.io/"><FONT COLOR="#000060">PCP Site</FONT></A><BR>Copyright © 2012-2014 <A HREF="http://www.redhat.com/"><FONT COLOR="#000060">Red Hat</FONT></P></TD> </TR> +</TABLE> +</CENTER> +</BODY> +</HTML> diff --git a/man/html/images/GNUmakefile b/man/html/images/GNUmakefile new file mode 100644 index 0000000..ee2b571 --- /dev/null +++ b/man/html/images/GNUmakefile @@ -0,0 +1,27 @@ +TOPDIR = ../../.. +include $(TOPDIR)/src/include/builddefs + +ICOFILES = $(shell echo *.ico) +PNGFILES = $(shell echo *.png) +SVGFILES = $(shell echo *.svg) +LSRCFILES = $(ICOFILES) $(PNGFILES) $(SVGFILES) +ICONLINKS = pcpicon.png pmcharticon.png pmtimeicon.png stepfwd_on.png system-search.png +INSTFILES = $(shell echo $(ICONLINKS) $(ICOFILES) $(PNGFILES) | tr ' ' '\n' | sort -u) +LDIRT = $(ICONLINKS) + +default: + @for l in $(ICONLINKS) ; do \ + if [ ! -L $$l -a ! -f $$l ] ; then \ + $(LN_S) $(TOPDIR)/images/$$l $$l ; \ + fi \ + done + +include $(BUILDRULES) + +install: default + $(INSTALL) -m 755 -d $(PCP_BOOKS_DIR)/html/images + $(INSTALL) -m 644 $(INSTFILES) $(PCP_BOOKS_DIR)/html/images + +default_pcp : default + +install_pcp : install diff --git a/man/html/images/cpu_pswitch.png b/man/html/images/cpu_pswitch.png Binary files differnew file mode 100644 index 0000000..de38e36 --- /dev/null +++ b/man/html/images/cpu_pswitch.png diff --git a/man/html/images/dkvis.png b/man/html/images/dkvis.png Binary files differnew file mode 100644 index 0000000..cd95ccc --- /dev/null +++ b/man/html/images/dkvis.png diff --git a/man/html/images/elasticsearch.png b/man/html/images/elasticsearch.png Binary files differnew file mode 100644 index 0000000..536235b --- /dev/null +++ b/man/html/images/elasticsearch.png diff --git a/man/html/images/model_biload.png b/man/html/images/model_biload.png Binary files differnew file mode 100644 index 0000000..defd12b --- /dev/null +++ b/man/html/images/model_biload.png diff --git a/man/html/images/model_dbload.png b/man/html/images/model_dbload.png Binary files differnew file mode 100644 index 0000000..1caaf8f --- /dev/null +++ b/man/html/images/model_dbload.png diff --git a/man/html/images/model_nasload.png b/man/html/images/model_nasload.png Binary files differnew file mode 100644 index 0000000..258a2b8 --- /dev/null +++ b/man/html/images/model_nasload.png diff --git a/man/html/images/model_spreadsheet.png b/man/html/images/model_spreadsheet.png Binary files differnew file mode 100644 index 0000000..c6b3107 --- /dev/null +++ b/man/html/images/model_spreadsheet.png diff --git a/man/html/images/mover.nfile.counter.3min.png b/man/html/images/mover.nfile.counter.3min.png Binary files differnew file mode 100644 index 0000000..5210982 --- /dev/null +++ b/man/html/images/mover.nfile.counter.3min.png diff --git a/man/html/images/mover.nfile.counter.png b/man/html/images/mover.nfile.counter.png Binary files differnew file mode 100644 index 0000000..8231a96 --- /dev/null +++ b/man/html/images/mover.nfile.counter.png diff --git a/man/html/images/mover.nfile.instant.3min.png b/man/html/images/mover.nfile.instant.3min.png Binary files differnew file mode 100644 index 0000000..706674c --- /dev/null +++ b/man/html/images/mover.nfile.instant.3min.png diff --git a/man/html/images/mover.nfile.instant.png b/man/html/images/mover.nfile.instant.png Binary files differnew file mode 100644 index 0000000..a56ec8a --- /dev/null +++ b/man/html/images/mover.nfile.instant.png diff --git a/man/html/images/mover.nfile.step.png b/man/html/images/mover.nfile.step.png Binary files differnew file mode 100644 index 0000000..60c860f --- /dev/null +++ b/man/html/images/mover.nfile.step.png diff --git a/man/html/images/mover.png b/man/html/images/mover.png Binary files differnew file mode 100644 index 0000000..3504066 --- /dev/null +++ b/man/html/images/mover.png diff --git a/man/html/images/mover.v3.png b/man/html/images/mover.v3.png Binary files differnew file mode 100644 index 0000000..27df465 --- /dev/null +++ b/man/html/images/mover.v3.png diff --git a/man/html/images/mpvis.png b/man/html/images/mpvis.png Binary files differnew file mode 100644 index 0000000..2338528 --- /dev/null +++ b/man/html/images/mpvis.png diff --git a/man/html/images/ovevents.png b/man/html/images/ovevents.png Binary files differnew file mode 100644 index 0000000..d47dc45 --- /dev/null +++ b/man/html/images/ovevents.png diff --git a/man/html/images/pcp.ico b/man/html/images/pcp.ico Binary files differnew file mode 100644 index 0000000..168721e --- /dev/null +++ b/man/html/images/pcp.ico diff --git a/man/html/images/pmchart_add_host_secure.png b/man/html/images/pmchart_add_host_secure.png Binary files differnew file mode 100644 index 0000000..b819d34 --- /dev/null +++ b/man/html/images/pmchart_add_host_secure.png diff --git a/man/html/images/pmchart_blank_canvas.png b/man/html/images/pmchart_blank_canvas.png Binary files differnew file mode 100644 index 0000000..81d1943 --- /dev/null +++ b/man/html/images/pmchart_blank_canvas.png diff --git a/man/html/images/pmchart_cpu_disk.png b/man/html/images/pmchart_cpu_disk.png Binary files differnew file mode 100644 index 0000000..c5cea8a --- /dev/null +++ b/man/html/images/pmchart_cpu_disk.png diff --git a/man/html/images/pmchart_cpu_disk_load.png b/man/html/images/pmchart_cpu_disk_load.png Binary files differnew file mode 100644 index 0000000..b8c2669 --- /dev/null +++ b/man/html/images/pmchart_cpu_disk_load.png diff --git a/man/html/images/pmchart_cpu_disk_record.png b/man/html/images/pmchart_cpu_disk_record.png Binary files differnew file mode 100644 index 0000000..f6614da --- /dev/null +++ b/man/html/images/pmchart_cpu_disk_record.png diff --git a/man/html/images/pmchart_edit_chart.png b/man/html/images/pmchart_edit_chart.png Binary files differnew file mode 100644 index 0000000..1502d5e --- /dev/null +++ b/man/html/images/pmchart_edit_chart.png diff --git a/man/html/images/pmchart_new_chart.png b/man/html/images/pmchart_new_chart.png Binary files differnew file mode 100644 index 0000000..874632e --- /dev/null +++ b/man/html/images/pmchart_new_chart.png diff --git a/man/html/images/pmchart_new_chart_colors.png b/man/html/images/pmchart_new_chart_colors.png Binary files differnew file mode 100644 index 0000000..9fc6b7c --- /dev/null +++ b/man/html/images/pmchart_new_chart_colors.png diff --git a/man/html/images/pmchart_new_chart_select.png b/man/html/images/pmchart_new_chart_select.png Binary files differnew file mode 100644 index 0000000..2592497 --- /dev/null +++ b/man/html/images/pmchart_new_chart_select.png diff --git a/man/html/images/pmchart_open_view.png b/man/html/images/pmchart_open_view.png Binary files differnew file mode 100644 index 0000000..1a9f5a8 --- /dev/null +++ b/man/html/images/pmchart_open_view.png diff --git a/man/html/images/pmchart_stop_recording.png b/man/html/images/pmchart_stop_recording.png Binary files differnew file mode 100644 index 0000000..54a94a2 --- /dev/null +++ b/man/html/images/pmchart_stop_recording.png diff --git a/man/html/images/pmie_axis1.png b/man/html/images/pmie_axis1.png Binary files differnew file mode 100644 index 0000000..8c6be80 --- /dev/null +++ b/man/html/images/pmie_axis1.png diff --git a/man/html/images/pmie_axis2.png b/man/html/images/pmie_axis2.png Binary files differnew file mode 100644 index 0000000..719f6fc --- /dev/null +++ b/man/html/images/pmie_axis2.png diff --git a/man/html/images/pmie_axis3.png b/man/html/images/pmie_axis3.png Binary files differnew file mode 100644 index 0000000..a671a1c --- /dev/null +++ b/man/html/images/pmie_axis3.png diff --git a/man/html/images/pmie_axis4.png b/man/html/images/pmie_axis4.png Binary files differnew file mode 100644 index 0000000..05faabd --- /dev/null +++ b/man/html/images/pmie_axis4.png diff --git a/man/html/images/pmie_rule1.png b/man/html/images/pmie_rule1.png Binary files differnew file mode 100644 index 0000000..3ae47a4 --- /dev/null +++ b/man/html/images/pmie_rule1.png diff --git a/man/html/images/pmie_rule1.svg b/man/html/images/pmie_rule1.svg new file mode 100644 index 0000000..5a030a6 --- /dev/null +++ b/man/html/images/pmie_rule1.svg @@ -0,0 +1,221 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!-- Created with Inkscape (http://www.inkscape.org/) --> + +<svg + xmlns:dc="http://purl.org/dc/elements/1.1/" + xmlns:cc="http://creativecommons.org/ns#" + xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" + xmlns:svg="http://www.w3.org/2000/svg" + xmlns="http://www.w3.org/2000/svg" + xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" + xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" + width="495" + height="200" + id="svg2" + version="1.1" + inkscape:version="0.47 r22583" + sodipodi:docname="pmie_rule1.svg" + inkscape:export-filename="/source/git/nathans/pcp-gui/man/html/images/pmie_rule1.png" + inkscape:export-xdpi="90" + inkscape:export-ydpi="90"> + <defs + id="defs4"> + <inkscape:perspective + sodipodi:type="inkscape:persp3d" + inkscape:vp_x="0 : 526.18109 : 1" + inkscape:vp_y="0 : 1000 : 0" + inkscape:vp_z="744.09448 : 526.18109 : 1" + inkscape:persp3d-origin="372.04724 : 350.78739 : 1" + id="perspective10" /> + <inkscape:perspective + id="perspective4112" + inkscape:persp3d-origin="0.5 : 0.33333333 : 1" + inkscape:vp_z="1 : 0.5 : 1" + inkscape:vp_y="0 : 1000 : 0" + inkscape:vp_x="0 : 0.5 : 1" + sodipodi:type="inkscape:persp3d" /> + <inkscape:perspective + id="perspective4112-1" + inkscape:persp3d-origin="0.5 : 0.33333333 : 1" + inkscape:vp_z="1 : 0.5 : 1" + inkscape:vp_y="0 : 1000 : 0" + inkscape:vp_x="0 : 0.5 : 1" + sodipodi:type="inkscape:persp3d" /> + </defs> + <sodipodi:namedview + id="base" + pagecolor="#ffffff" + bordercolor="#666666" + borderopacity="1.0" + inkscape:pageopacity="0.0" + inkscape:pageshadow="2" + inkscape:zoom="0.7" + inkscape:cx="224.56281" + inkscape:cy="133.99048" + inkscape:document-units="px" + inkscape:current-layer="layer1" + showgrid="false" /> + <metadata + id="metadata7"> + <rdf:RDF> + <cc:Work + rdf:about=""> + <dc:format>image/svg+xml</dc:format> + <dc:type + rdf:resource="http://purl.org/dc/dcmitype/StillImage" /> + <dc:title /> + </cc:Work> + </rdf:RDF> + </metadata> + <g + inkscape:label="Layer 1" + inkscape:groupmode="layer" + id="layer1" + transform="translate(0,-852.36218)"> + <rect + style="fill:#ffffff;fill-opacity:1;fill-rule:nonzero;stroke:#f80824;stroke-width:4.22632027;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" + id="rect3592" + width="467.9165" + height="77.91655" + x="15.327446" + y="913.9754" /> + <text + xml:space="preserve" + style="font-size:24;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;fill:#000000;fill-opacity:1;stroke:none;font-family:FreeSans;-inkscape-font-specification:FreeSans" + x="74.285713" + y="88.571426" + id="text3596" + transform="translate(0,852.36218)"><tspan + sodipodi:role="line" + id="tspan3598" + x="74.285713" + y="88.571426" /></text> + <text + xml:space="preserve" + style="font-size:24px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;fill:#000000;fill-opacity:1;stroke:none;font-family:FreeSans;-inkscape-font-specification:FreeSans" + x="41.142857" + y="945.79077" + id="text3600"><tspan + sodipodi:role="line" + id="tspan3602" + x="41.142857" + y="945.79077" + style="font-weight:bold">kernel.all.pswitch <tspan + style="font-weight:bold;fill:#ff031d;fill-opacity:1" + id="tspan3606">></tspan> 2000 <tspan + style="font-weight:bold;fill:#ff0000;fill-opacity:1" + id="tspan3654">count / sec</tspan></tspan><tspan + sodipodi:role="line" + x="41.142857" + y="975.79077" + id="tspan3604" + style="font-weight:bold"><tspan + style="font-weight:bold;fill:#ff0000;fill-opacity:1" + id="tspan3656">-> alarm</tspan> "high context switch rate" <tspan + style="font-weight:bold;fill:#ed071b;fill-opacity:1" + id="tspan4086">;</tspan></tspan></text> + <text + xml:space="preserve" + style="font-size:24px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;fill:#000000;fill-opacity:1;stroke:none;font-family:FreeSans;-inkscape-font-specification:FreeSans" + x="14.285715" + y="880.93359" + id="text4088"><tspan + sodipodi:role="line" + id="tspan4090" + x="14.285715" + y="880.93359">performance metric</tspan></text> + <text + xml:space="preserve" + style="font-size:24px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;fill:#000000;fill-opacity:1;stroke:none;font-family:FreeSans;-inkscape-font-specification:FreeSans" + x="288.57144" + y="879.50507" + id="text4092"><tspan + sodipodi:role="line" + id="tspan4094" + x="288.57144" + y="879.50507">constant with units</tspan></text> + <text + xml:space="preserve" + style="font-size:24px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;fill:#000000;fill-opacity:1;stroke:none;font-family:FreeSans;-inkscape-font-specification:FreeSans" + x="37.142853" + y="1040.9336" + id="text4096"><tspan + sodipodi:role="line" + id="tspan4098" + x="37.142853" + y="1040.9336">alarm action</tspan></text> + <g + id="g4148" + transform="matrix(0.96193666,-0.30935215,0.20916655,0.89635456,-156.58435,196.99713)" + style="opacity:0.89699557;fill:#ed071b;fill-opacity:1;stroke:#ff0012;stroke-opacity:1"> + <path + transform="matrix(1.0357578,0,0,0.99567281,61.624303,918.25692)" + d="m 28.571429,-81.428574 c -2.165063,0.61859 -4.854737,-4.697115 -6.472983,-6.26282 -1.618246,-1.565706 -7.019802,-4.078527 -6.472985,-6.262822 0.546818,-2.184294 6.495191,-1.855768 8.660254,-2.474358 2.165064,-0.618589 7.042009,-4.040066 8.660255,-2.474358 1.618246,1.565705 -1.640453,6.552884 -2.18727,8.737179 -0.546818,2.184295 -0.02221,8.11859 -2.187271,8.737179 z" + inkscape:randomized="0" + inkscape:rounded="0.25" + inkscape:flatsided="false" + sodipodi:arg2="2.3396942" + sodipodi:arg1="1.2924967" + sodipodi:r2="5.2000785" + sodipodi:r1="10.400157" + sodipodi:cy="-91.428574" + sodipodi:cx="25.714287" + sodipodi:sides="3" + id="path4100" + style="fill:#ed071b;fill-opacity:1;fill-rule:nonzero;stroke:#ff0012;stroke-width:5;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" + sodipodi:type="star" /> + <path + id="path4102" + d="M 86.592933,821.58384 76.819617,792.88455" + style="fill:#ed071b;fill-opacity:1;stroke:#ff0012;stroke-width:3;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" /> + </g> + <g + id="g4144" + transform="matrix(0.51602266,0.85657493,-0.85657493,0.51602266,976.61315,331.26048)"> + <path + transform="matrix(1.0357578,0,0,0.99567281,156.06321,919.32798)" + d="m 28.571429,-81.428574 c -2.165063,0.61859 -4.854737,-4.697115 -6.472983,-6.26282 -1.618246,-1.565706 -7.019802,-4.078527 -6.472985,-6.262822 0.546818,-2.184294 6.495191,-1.855768 8.660254,-2.474358 2.165064,-0.618589 7.042009,-4.040066 8.660255,-2.474358 1.618246,1.565705 -1.640453,6.552884 -2.18727,8.737179 -0.546818,2.184295 -0.02221,8.11859 -2.187271,8.737179 z" + inkscape:randomized="0" + inkscape:rounded="0.25" + inkscape:flatsided="false" + sodipodi:arg2="2.3396942" + sodipodi:arg1="1.2924967" + sodipodi:r2="5.2000785" + sodipodi:r1="10.400157" + sodipodi:cy="-91.428574" + sodipodi:cx="25.714287" + sodipodi:sides="3" + id="path4100-8" + style="fill:#ed071b;fill-opacity:1;fill-rule:nonzero;stroke:#f80824;stroke-width:5;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" + sodipodi:type="star" /> + <path + id="path4102-2" + d="m 181.03184,822.6549 -9.77332,-28.69929" + style="fill:none;stroke:#ff0012;stroke-width:3;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" /> + </g> + <g + id="g4140" + transform="matrix(-0.72568113,-0.68803117,0.68803117,-0.72568113,-251.94582,1773.1963)"> + <path + transform="matrix(1.0357578,0,0,0.99567281,247.49178,907.18513)" + d="m 28.571429,-81.428574 c -2.165063,0.61859 -4.854737,-4.697115 -6.472983,-6.26282 -1.618246,-1.565706 -7.019802,-4.078527 -6.472985,-6.262822 0.546818,-2.184294 6.495191,-1.855768 8.660254,-2.474358 2.165064,-0.618589 7.042009,-4.040066 8.660255,-2.474358 1.618246,1.565705 -1.640453,6.552884 -2.18727,8.737179 -0.546818,2.184295 -0.02221,8.11859 -2.187271,8.737179 z" + inkscape:randomized="0" + inkscape:rounded="0.25" + inkscape:flatsided="false" + sodipodi:arg2="2.3396942" + sodipodi:arg1="1.2924967" + sodipodi:r2="5.2000785" + sodipodi:r1="10.400157" + sodipodi:cy="-91.428574" + sodipodi:cx="25.714287" + sodipodi:sides="3" + id="path4100-0" + style="fill:#ed071b;fill-opacity:1;fill-rule:nonzero;stroke:#f80824;stroke-width:5;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" + sodipodi:type="star" /> + <path + id="path4102-5" + d="m 272.46041,810.51205 -9.77332,-28.69929" + style="fill:none;stroke:#ff0012;stroke-width:3;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" /> + </g> + </g> +</svg> diff --git a/man/html/images/pmie_rule2.png b/man/html/images/pmie_rule2.png Binary files differnew file mode 100644 index 0000000..2acc517 --- /dev/null +++ b/man/html/images/pmie_rule2.png diff --git a/man/html/images/pmie_rule2.svg b/man/html/images/pmie_rule2.svg new file mode 100644 index 0000000..c600382 --- /dev/null +++ b/man/html/images/pmie_rule2.svg @@ -0,0 +1,224 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!-- Created with Inkscape (http://www.inkscape.org/) --> + +<svg + xmlns:dc="http://purl.org/dc/elements/1.1/" + xmlns:cc="http://creativecommons.org/ns#" + xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" + xmlns:svg="http://www.w3.org/2000/svg" + xmlns="http://www.w3.org/2000/svg" + xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" + xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" + width="495" + height="200" + id="svg2" + version="1.1" + inkscape:version="0.47 r22583" + sodipodi:docname="pmie_rule2.svg" + inkscape:export-filename="/source/git/nathans/pcp-gui/man/html/images/pmie_rule2.png" + inkscape:export-xdpi="90" + inkscape:export-ydpi="90"> + <defs + id="defs4"> + <inkscape:perspective + sodipodi:type="inkscape:persp3d" + inkscape:vp_x="0 : 526.18109 : 1" + inkscape:vp_y="0 : 1000 : 0" + inkscape:vp_z="744.09448 : 526.18109 : 1" + inkscape:persp3d-origin="372.04724 : 350.78739 : 1" + id="perspective10" /> + <inkscape:perspective + id="perspective4112" + inkscape:persp3d-origin="0.5 : 0.33333333 : 1" + inkscape:vp_z="1 : 0.5 : 1" + inkscape:vp_y="0 : 1000 : 0" + inkscape:vp_x="0 : 0.5 : 1" + sodipodi:type="inkscape:persp3d" /> + <inkscape:perspective + id="perspective4112-1" + inkscape:persp3d-origin="0.5 : 0.33333333 : 1" + inkscape:vp_z="1 : 0.5 : 1" + inkscape:vp_y="0 : 1000 : 0" + inkscape:vp_x="0 : 0.5 : 1" + sodipodi:type="inkscape:persp3d" /> + <inkscape:perspective + id="perspective2853" + inkscape:persp3d-origin="0.5 : 0.33333333 : 1" + inkscape:vp_z="1 : 0.5 : 1" + inkscape:vp_y="0 : 1000 : 0" + inkscape:vp_x="0 : 0.5 : 1" + sodipodi:type="inkscape:persp3d" /> + <inkscape:perspective + id="perspective2853-2" + inkscape:persp3d-origin="0.5 : 0.33333333 : 1" + inkscape:vp_z="1 : 0.5 : 1" + inkscape:vp_y="0 : 1000 : 0" + inkscape:vp_x="0 : 0.5 : 1" + sodipodi:type="inkscape:persp3d" /> + </defs> + <sodipodi:namedview + id="base" + pagecolor="#ffffff" + bordercolor="#666666" + borderopacity="1.0" + inkscape:pageopacity="0.0" + inkscape:pageshadow="2" + inkscape:zoom="0.7" + inkscape:cx="296.56459" + inkscape:cy="133.99048" + inkscape:document-units="px" + inkscape:current-layer="layer1" + showgrid="false" /> + <metadata + id="metadata7"> + <rdf:RDF> + <cc:Work + rdf:about=""> + <dc:format>image/svg+xml</dc:format> + <dc:type + rdf:resource="http://purl.org/dc/dcmitype/StillImage" /> + <dc:title /> + </cc:Work> + </rdf:RDF> + </metadata> + <g + inkscape:label="Layer 1" + inkscape:groupmode="layer" + id="layer1" + transform="translate(0,-852.36218)"> + <rect + style="fill:#ffffff;fill-opacity:1;fill-rule:nonzero;stroke:#f80824;stroke-width:4.22632027;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" + id="rect3592" + width="467.9165" + height="77.91655" + x="15.327446" + y="859.9754" /> + <text + xml:space="preserve" + style="font-size:24;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;fill:#000000;fill-opacity:1;stroke:none;font-family:FreeSans;-inkscape-font-specification:FreeSans" + x="74.285713" + y="88.571426" + id="text3596" + transform="translate(0,852.36218)"><tspan + sodipodi:role="line" + id="tspan3598" + x="74.285713" + y="88.571426" /></text> + <text + xml:space="preserve" + style="font-size:24px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;fill:#000000;fill-opacity:1;stroke:none;font-family:FreeSans;-inkscape-font-specification:FreeSans" + x="41.142857" + y="889.79077" + id="text3600"><tspan + sodipodi:role="line" + id="tspan3602" + x="41.142857" + y="889.79077" + style="font-weight:bold">kernel.all.pswitch <tspan + style="font-weight:bold;fill:#ff031d;fill-opacity:1" + id="tspan3606">></tspan> 2000 <tspan + style="font-weight:bold;fill:#ff0000;fill-opacity:1" + id="tspan3654">count / sec</tspan></tspan><tspan + sodipodi:role="line" + x="41.142857" + y="919.79077" + id="tspan3604" + style="font-weight:bold"><tspan + style="font-weight:bold;fill:#ff0000;fill-opacity:1" + id="tspan3656">-> shell <tspan + style="fill:#2b0000" + id="tspan2839">5</tspan> min</tspan> " xterm -e 'top' " <tspan + style="font-weight:bold;fill:#ed071b;fill-opacity:1" + id="tspan4086">;</tspan></tspan></text> + <text + xml:space="preserve" + style="font-size:24px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;fill:#000000;fill-opacity:1;stroke:none;font-family:FreeSans;-inkscape-font-specification:FreeSans" + x="227.14285" + y="989.79071" + id="text4088"><tspan + sodipodi:role="line" + id="tspan4090" + x="227.14285" + y="989.79071">program to execute</tspan></text> + <text + xml:space="preserve" + style="font-size:24px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;fill:#000000;fill-opacity:1;stroke:none;font-family:FreeSans;-inkscape-font-specification:FreeSans" + x="120.00002" + y="1014.3622" + id="text4092"><tspan + sodipodi:role="line" + id="tspan4094" + x="120.00002" + y="1014.3622">hold off repetition</tspan></text> + <text + xml:space="preserve" + style="font-size:24px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;fill:#000000;fill-opacity:1;stroke:none;font-family:FreeSans;-inkscape-font-specification:FreeSans" + x="22.857138" + y="1037.2194" + id="text4096"><tspan + sodipodi:role="line" + id="tspan4098" + x="22.857138" + y="1037.2194">launch program</tspan></text> + <path + sodipodi:type="star" + style="fill:#ed071b;fill-opacity:1;fill-rule:nonzero;stroke:#f80824;stroke-width:5;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" + id="path4100-0" + sodipodi:sides="3" + sodipodi:cx="25.714287" + sodipodi:cy="-91.428574" + sodipodi:r1="10.400157" + sodipodi:r2="5.2000785" + sodipodi:arg1="1.2924967" + sodipodi:arg2="2.3396942" + inkscape:flatsided="false" + inkscape:rounded="0.25" + inkscape:randomized="0" + d="m 28.571429,-81.428574 c -2.165063,0.61859 -4.854737,-4.697115 -6.472983,-6.26282 -1.618246,-1.565706 -7.019802,-4.078527 -6.472985,-6.262822 0.546818,-2.184294 6.495191,-1.855768 8.660254,-2.474358 2.165064,-0.618589 7.042009,-4.040066 8.660255,-2.474358 1.618246,1.565705 -1.640453,6.552884 -2.18727,8.737179 -0.546818,2.184295 -0.02221,8.11859 -2.187271,8.737179 z" + transform="matrix(-0.89164349,-0.31095083,0.35210688,-1.0338078,137.43382,855.97071)" /> + <path + style="fill:none;stroke:#ff0012;stroke-width:3.528018;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" + d="m 81.488096,949.11447 -1.207647,65.06173" + id="path4102-5" /> + <path + sodipodi:type="star" + style="fill:#ed071b;fill-opacity:1;fill-rule:nonzero;stroke:#f80824;stroke-width:5;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" + id="path4100-0-6" + sodipodi:sides="3" + sodipodi:cx="25.714287" + sodipodi:cy="-91.428574" + sodipodi:r1="10.400157" + sodipodi:r2="5.2000785" + sodipodi:arg1="1.2924967" + sodipodi:arg2="2.3396942" + inkscape:flatsided="false" + inkscape:rounded="0.25" + inkscape:randomized="0" + d="m 28.571429,-81.428574 c -2.165063,0.61859 -4.854737,-4.697115 -6.472983,-6.26282 -1.618246,-1.565706 -7.019802,-4.078527 -6.472985,-6.262822 0.546818,-2.184294 6.495191,-1.855768 8.660254,-2.474358 2.165064,-0.618589 7.042009,-4.040066 8.660255,-2.474358 1.618246,1.565705 -1.640453,6.552884 -2.18727,8.737179 -0.546818,2.184295 -0.02221,8.11859 -2.187271,8.737179 z" + transform="matrix(-0.89164349,-0.31095083,0.35210688,-1.0338078,216.96942,855.9983)" /> + <path + style="fill:none;stroke:#ff0012;stroke-width:3.20799208;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" + d="m 161.18371,948.98205 -1.52767,42.52462" + id="path4102-5-3" /> + <path + sodipodi:type="star" + style="fill:#ed071b;fill-opacity:1;fill-rule:nonzero;stroke:#f80824;stroke-width:5;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" + id="path4100-0-0" + sodipodi:sides="3" + sodipodi:cx="25.714287" + sodipodi:cy="-91.428574" + sodipodi:r1="10.400157" + sodipodi:r2="5.2000785" + sodipodi:arg1="1.2924967" + sodipodi:arg2="2.3396942" + inkscape:flatsided="false" + inkscape:rounded="0.25" + inkscape:randomized="0" + d="m 28.571429,-81.428574 c -2.165063,0.61859 -4.854737,-4.697115 -6.472983,-6.26282 -1.618246,-1.565706 -7.019802,-4.078527 -6.472985,-6.262822 0.546818,-2.184294 6.495191,-1.855768 8.660254,-2.474358 2.165064,-0.618589 7.042009,-4.040066 8.660255,-2.474358 1.618246,1.565705 -1.640453,6.552884 -2.18727,8.737179 -0.546818,2.184295 -0.02221,8.11859 -2.187271,8.737179 z" + transform="matrix(-0.89164349,-0.31095083,0.35210688,-1.0338078,319.82657,856.56973)" /> + <path + style="fill:none;stroke:#ff0012;stroke-width:2.61137056;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" + d="m 263.66469,949.20703 -0.77533,20.36035" + id="path4102-5-6" /> + </g> +</svg> diff --git a/man/html/images/pmie_rule3.png b/man/html/images/pmie_rule3.png Binary files differnew file mode 100644 index 0000000..a11ef45 --- /dev/null +++ b/man/html/images/pmie_rule3.png diff --git a/man/html/images/pmie_rule3.svg b/man/html/images/pmie_rule3.svg new file mode 100644 index 0000000..243ef2f --- /dev/null +++ b/man/html/images/pmie_rule3.svg @@ -0,0 +1,139 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!-- Created with Inkscape (http://www.inkscape.org/) --> + +<svg + xmlns:dc="http://purl.org/dc/elements/1.1/" + xmlns:cc="http://creativecommons.org/ns#" + xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" + xmlns:svg="http://www.w3.org/2000/svg" + xmlns="http://www.w3.org/2000/svg" + xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" + xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" + width="495" + height="120" + id="svg2" + version="1.1" + inkscape:version="0.47 r22583" + sodipodi:docname="pmie_rule3.svg" + inkscape:export-filename="/source/git/nathans/pcp-gui/man/html/images/pmie_rule3.png" + inkscape:export-xdpi="90" + inkscape:export-ydpi="90"> + <defs + id="defs4"> + <inkscape:perspective + sodipodi:type="inkscape:persp3d" + inkscape:vp_x="0 : 526.18109 : 1" + inkscape:vp_y="0 : 1000 : 0" + inkscape:vp_z="744.09448 : 526.18109 : 1" + inkscape:persp3d-origin="372.04724 : 350.78739 : 1" + id="perspective10" /> + <inkscape:perspective + id="perspective4112" + inkscape:persp3d-origin="0.5 : 0.33333333 : 1" + inkscape:vp_z="1 : 0.5 : 1" + inkscape:vp_y="0 : 1000 : 0" + inkscape:vp_x="0 : 0.5 : 1" + sodipodi:type="inkscape:persp3d" /> + <inkscape:perspective + id="perspective4112-1" + inkscape:persp3d-origin="0.5 : 0.33333333 : 1" + inkscape:vp_z="1 : 0.5 : 1" + inkscape:vp_y="0 : 1000 : 0" + inkscape:vp_x="0 : 0.5 : 1" + sodipodi:type="inkscape:persp3d" /> + <inkscape:perspective + id="perspective2853" + inkscape:persp3d-origin="0.5 : 0.33333333 : 1" + inkscape:vp_z="1 : 0.5 : 1" + inkscape:vp_y="0 : 1000 : 0" + inkscape:vp_x="0 : 0.5 : 1" + sodipodi:type="inkscape:persp3d" /> + <inkscape:perspective + id="perspective2853-2" + inkscape:persp3d-origin="0.5 : 0.33333333 : 1" + inkscape:vp_z="1 : 0.5 : 1" + inkscape:vp_y="0 : 1000 : 0" + inkscape:vp_x="0 : 0.5 : 1" + sodipodi:type="inkscape:persp3d" /> + </defs> + <sodipodi:namedview + id="base" + pagecolor="#ffffff" + bordercolor="#666666" + borderopacity="1.0" + inkscape:pageopacity="0.0" + inkscape:pageshadow="2" + inkscape:zoom="0.7" + inkscape:cx="334.18561" + inkscape:cy="133.99048" + inkscape:document-units="px" + inkscape:current-layer="layer1" + showgrid="false" /> + <metadata + id="metadata7"> + <rdf:RDF> + <cc:Work + rdf:about=""> + <dc:format>image/svg+xml</dc:format> + <dc:type + rdf:resource="http://purl.org/dc/dcmitype/StillImage" /> + <dc:title /> + </cc:Work> + </rdf:RDF> + </metadata> + <g + inkscape:label="Layer 1" + inkscape:groupmode="layer" + id="layer1" + transform="translate(0,-932.36218)"> + <rect + style="fill:#ffffff;fill-opacity:1;fill-rule:nonzero;stroke:#f80824;stroke-width:4.88859749;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" + id="rect3592" + width="467.25424" + height="104.39713" + x="15.658585" + y="940.30652" /> + <text + xml:space="preserve" + style="font-size:24px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;fill:#000000;fill-opacity:1;stroke:none;font-family:FreeSans;-inkscape-font-specification:FreeSans" + x="74.285713" + y="88.571426" + id="text3596" + transform="translate(0,852.36218)"><tspan + sodipodi:role="line" + id="tspan3598" + x="74.285713" + y="88.571426" /></text> + <text + xml:space="preserve" + style="font-size:24px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;fill:#000000;fill-opacity:1;stroke:none;font-family:FreeSans;-inkscape-font-specification:FreeSans" + x="51.142857" + y="969.79077" + id="text3600"><tspan + sodipodi:role="line" + id="tspan3602" + x="51.142857" + y="969.79077" + style="font-weight:bold">some_inst</tspan><tspan + sodipodi:role="line" + x="51.142857" + y="999.79077" + style="font-weight:bold" + id="tspan2840"> disk.dev.total <tspan + style="font-weight:bold;fill:#ff031d;fill-opacity:1" + id="tspan3606">></tspan> 30 <tspan + style="font-weight:bold;fill:#ff0000;fill-opacity:1" + id="tspan3654">count / sec</tspan></tspan><tspan + sodipodi:role="line" + x="51.142857" + y="1029.7908" + id="tspan3604" + style="font-weight:bold"><tspan + style="font-weight:bold;fill:#ff0000;fill-opacity:1" + id="tspan3656">-> alarm <tspan + style="fill:#2b0000" + id="tspan2839">5</tspan> mins</tspan> "very busy disks"<tspan + style="font-weight:bold;fill:#ed071b;fill-opacity:1" + id="tspan4086">;</tspan></tspan></text> + </g> +</svg> diff --git a/man/html/images/pmie_rule4.png b/man/html/images/pmie_rule4.png Binary files differnew file mode 100644 index 0000000..eadd6c3 --- /dev/null +++ b/man/html/images/pmie_rule4.png diff --git a/man/html/images/pmie_rule4.svg b/man/html/images/pmie_rule4.svg new file mode 100644 index 0000000..ed29ea9 --- /dev/null +++ b/man/html/images/pmie_rule4.svg @@ -0,0 +1,146 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!-- Created with Inkscape (http://www.inkscape.org/) --> + +<svg + xmlns:dc="http://purl.org/dc/elements/1.1/" + xmlns:cc="http://creativecommons.org/ns#" + xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" + xmlns:svg="http://www.w3.org/2000/svg" + xmlns="http://www.w3.org/2000/svg" + xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" + xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" + width="540" + height="140" + id="svg2" + version="1.1" + inkscape:version="0.47 r22583" + sodipodi:docname="pmie_rule4.svg" + inkscape:export-filename="/source/git/nathans/pcp-gui/man/html/images/pmie_rule4.png" + inkscape:export-xdpi="90" + inkscape:export-ydpi="90"> + <defs + id="defs4"> + <inkscape:perspective + sodipodi:type="inkscape:persp3d" + inkscape:vp_x="0 : 526.18109 : 1" + inkscape:vp_y="0 : 1000 : 0" + inkscape:vp_z="744.09448 : 526.18109 : 1" + inkscape:persp3d-origin="372.04724 : 350.78739 : 1" + id="perspective10" /> + <inkscape:perspective + id="perspective4112" + inkscape:persp3d-origin="0.5 : 0.33333333 : 1" + inkscape:vp_z="1 : 0.5 : 1" + inkscape:vp_y="0 : 1000 : 0" + inkscape:vp_x="0 : 0.5 : 1" + sodipodi:type="inkscape:persp3d" /> + <inkscape:perspective + id="perspective4112-1" + inkscape:persp3d-origin="0.5 : 0.33333333 : 1" + inkscape:vp_z="1 : 0.5 : 1" + inkscape:vp_y="0 : 1000 : 0" + inkscape:vp_x="0 : 0.5 : 1" + sodipodi:type="inkscape:persp3d" /> + <inkscape:perspective + id="perspective2853" + inkscape:persp3d-origin="0.5 : 0.33333333 : 1" + inkscape:vp_z="1 : 0.5 : 1" + inkscape:vp_y="0 : 1000 : 0" + inkscape:vp_x="0 : 0.5 : 1" + sodipodi:type="inkscape:persp3d" /> + <inkscape:perspective + id="perspective2853-2" + inkscape:persp3d-origin="0.5 : 0.33333333 : 1" + inkscape:vp_z="1 : 0.5 : 1" + inkscape:vp_y="0 : 1000 : 0" + inkscape:vp_x="0 : 0.5 : 1" + sodipodi:type="inkscape:persp3d" /> + </defs> + <sodipodi:namedview + id="base" + pagecolor="#ffffff" + bordercolor="#666666" + borderopacity="1.0" + inkscape:pageopacity="0.0" + inkscape:pageshadow="2" + inkscape:zoom="0.7" + inkscape:cx="266.3447" + inkscape:cy="133.99048" + inkscape:document-units="px" + inkscape:current-layer="layer1" + showgrid="false" /> + <metadata + id="metadata7"> + <rdf:RDF> + <cc:Work + rdf:about=""> + <dc:format>image/svg+xml</dc:format> + <dc:type + rdf:resource="http://purl.org/dc/dcmitype/StillImage" /> + <dc:title></dc:title> + </cc:Work> + </rdf:RDF> + </metadata> + <g + inkscape:label="Layer 1" + inkscape:groupmode="layer" + id="layer1" + transform="translate(0,-912.36218)"> + <rect + style="fill:#ffffff;fill-opacity:1;fill-rule:nonzero;stroke:#f80824;stroke-width:5.79608488;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" + id="rect3592" + width="524.91821" + height="130.63248" + x="8.3980427" + y="916.76025" /> + <text + xml:space="preserve" + style="font-size:24px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;fill:#000000;fill-opacity:1;stroke:none;font-family:FreeSans;-inkscape-font-specification:FreeSans" + x="74.285713" + y="88.571426" + id="text3596" + transform="translate(0,852.36218)"><tspan + sodipodi:role="line" + id="tspan3598" + x="74.285713" + y="88.571426" /></text> + <text + xml:space="preserve" + style="font-size:24px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;fill:#000000;fill-opacity:1;stroke:none;font-family:FreeSans;-inkscape-font-specification:FreeSans" + x="37.142857" + y="941.79077" + id="text3600"><tspan + sodipodi:role="line" + id="tspan3602" + x="37.142857" + y="941.79077" + style="font-weight:bold">all_sample</tspan><tspan + sodipodi:role="line" + x="37.142857" + y="971.79077" + style="font-weight:bold" + id="tspan2828"> ( some_inst</tspan><tspan + sodipodi:role="line" + x="37.142857" + y="1001.7908" + style="font-weight:bold" + id="tspan2840"> disk.dev.total @0..4 <tspan + style="font-weight:bold;fill:#ff031d;fill-opacity:1" + id="tspan3606">></tspan> 30 <tspan + style="font-weight:bold;fill:#ff0000;fill-opacity:1" + id="tspan3654">count / sec <tspan + style="font-weight:bold;fill:#2b0000;-inkscape-font-specification:Baekmuk Batang Bold" + id="tspan2837">)</tspan></tspan></tspan><tspan + sodipodi:role="line" + x="37.142857" + y="1031.7908" + id="tspan3604" + style="font-weight:bold"><tspan + style="font-weight:bold;fill:#ff0000;fill-opacity:1" + id="tspan3656">-> alarm <tspan + style="fill:#2b0000" + id="tspan2839">5</tspan> mins</tspan> "very busy disks"<tspan + style="font-weight:bold;fill:#ed071b;fill-opacity:1" + id="tspan4086">;</tspan></tspan></text> + </g> +</svg> diff --git a/man/html/images/pmie_rule5.png b/man/html/images/pmie_rule5.png Binary files differnew file mode 100644 index 0000000..77c0528 --- /dev/null +++ b/man/html/images/pmie_rule5.png diff --git a/man/html/images/pmie_rule5.svg b/man/html/images/pmie_rule5.svg new file mode 100644 index 0000000..4d725f8 --- /dev/null +++ b/man/html/images/pmie_rule5.svg @@ -0,0 +1,146 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!-- Created with Inkscape (http://www.inkscape.org/) --> + +<svg + xmlns:dc="http://purl.org/dc/elements/1.1/" + xmlns:cc="http://creativecommons.org/ns#" + xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" + xmlns:svg="http://www.w3.org/2000/svg" + xmlns="http://www.w3.org/2000/svg" + xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" + xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" + width="540" + height="140" + id="svg2" + version="1.1" + inkscape:version="0.47 r22583" + sodipodi:docname="pmie_rule5.svg" + inkscape:export-filename="/source/git/nathans/pcp-gui/man/html/images/pmie_rule5.png" + inkscape:export-xdpi="90" + inkscape:export-ydpi="90"> + <defs + id="defs4"> + <inkscape:perspective + sodipodi:type="inkscape:persp3d" + inkscape:vp_x="0 : 526.18109 : 1" + inkscape:vp_y="0 : 1000 : 0" + inkscape:vp_z="744.09448 : 526.18109 : 1" + inkscape:persp3d-origin="372.04724 : 350.78739 : 1" + id="perspective10" /> + <inkscape:perspective + id="perspective4112" + inkscape:persp3d-origin="0.5 : 0.33333333 : 1" + inkscape:vp_z="1 : 0.5 : 1" + inkscape:vp_y="0 : 1000 : 0" + inkscape:vp_x="0 : 0.5 : 1" + sodipodi:type="inkscape:persp3d" /> + <inkscape:perspective + id="perspective4112-1" + inkscape:persp3d-origin="0.5 : 0.33333333 : 1" + inkscape:vp_z="1 : 0.5 : 1" + inkscape:vp_y="0 : 1000 : 0" + inkscape:vp_x="0 : 0.5 : 1" + sodipodi:type="inkscape:persp3d" /> + <inkscape:perspective + id="perspective2853" + inkscape:persp3d-origin="0.5 : 0.33333333 : 1" + inkscape:vp_z="1 : 0.5 : 1" + inkscape:vp_y="0 : 1000 : 0" + inkscape:vp_x="0 : 0.5 : 1" + sodipodi:type="inkscape:persp3d" /> + <inkscape:perspective + id="perspective2853-2" + inkscape:persp3d-origin="0.5 : 0.33333333 : 1" + inkscape:vp_z="1 : 0.5 : 1" + inkscape:vp_y="0 : 1000 : 0" + inkscape:vp_x="0 : 0.5 : 1" + sodipodi:type="inkscape:persp3d" /> + </defs> + <sodipodi:namedview + id="base" + pagecolor="#ffffff" + bordercolor="#666666" + borderopacity="1.0" + inkscape:pageopacity="0.0" + inkscape:pageshadow="2" + inkscape:zoom="0.7" + inkscape:cx="266.3447" + inkscape:cy="76.847623" + inkscape:document-units="px" + inkscape:current-layer="layer1" + showgrid="false" /> + <metadata + id="metadata7"> + <rdf:RDF> + <cc:Work + rdf:about=""> + <dc:format>image/svg+xml</dc:format> + <dc:type + rdf:resource="http://purl.org/dc/dcmitype/StillImage" /> + <dc:title></dc:title> + </cc:Work> + </rdf:RDF> + </metadata> + <g + inkscape:label="Layer 1" + inkscape:groupmode="layer" + id="layer1" + transform="translate(0,-912.36218)"> + <rect + style="fill:#ffffff;fill-opacity:1;fill-rule:nonzero;stroke:#f80824;stroke-width:5.79608488;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" + id="rect3592" + width="524.91821" + height="130.63248" + x="8.3980427" + y="916.76025" /> + <text + xml:space="preserve" + style="font-size:24px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;fill:#000000;fill-opacity:1;stroke:none;font-family:FreeSans;-inkscape-font-specification:FreeSans" + x="74.285713" + y="88.571426" + id="text3596" + transform="translate(0,852.36218)"><tspan + sodipodi:role="line" + id="tspan3598" + x="74.285713" + y="88.571426" /></text> + <text + xml:space="preserve" + style="font-size:24px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;fill:#000000;fill-opacity:1;stroke:none;font-family:FreeSans;-inkscape-font-specification:FreeSans" + x="37.142857" + y="941.79077" + id="text3600"><tspan + sodipodi:role="line" + id="tspan3602" + x="37.142857" + y="941.79077" + style="font-weight:bold">some_inst</tspan><tspan + sodipodi:role="line" + x="37.142857" + y="971.79077" + style="font-weight:bold" + id="tspan2828"> ( all_sample</tspan><tspan + sodipodi:role="line" + x="37.142857" + y="1001.7908" + style="font-weight:bold" + id="tspan2840"> disk.dev.total @0..4 <tspan + style="font-weight:bold;fill:#ff031d;fill-opacity:1" + id="tspan3606">></tspan> 30 <tspan + style="font-weight:bold;fill:#ff0000;fill-opacity:1" + id="tspan3654">count / sec <tspan + style="font-weight:bold;fill:#2b0000;-inkscape-font-specification:Baekmuk Batang Bold" + id="tspan2837">)</tspan></tspan></tspan><tspan + sodipodi:role="line" + x="37.142857" + y="1031.7908" + id="tspan3604" + style="font-weight:bold"><tspan + style="font-weight:bold;fill:#ff0000;fill-opacity:1" + id="tspan3656">-> alarm <tspan + style="fill:#2b0000" + id="tspan2839">5</tspan> mins</tspan> "very busy disks"<tspan + style="font-weight:bold;fill:#ed071b;fill-opacity:1" + id="tspan4086">;</tspan></tspan></text> + </g> +</svg> diff --git a/man/html/images/pmie_rule6.png b/man/html/images/pmie_rule6.png Binary files differnew file mode 100644 index 0000000..c4a1463 --- /dev/null +++ b/man/html/images/pmie_rule6.png diff --git a/man/html/images/pmie_rule6.svg b/man/html/images/pmie_rule6.svg new file mode 100644 index 0000000..9b59bdb --- /dev/null +++ b/man/html/images/pmie_rule6.svg @@ -0,0 +1,137 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!-- Created with Inkscape (http://www.inkscape.org/) --> + +<svg + xmlns:dc="http://purl.org/dc/elements/1.1/" + xmlns:cc="http://creativecommons.org/ns#" + xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" + xmlns:svg="http://www.w3.org/2000/svg" + xmlns="http://www.w3.org/2000/svg" + xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" + xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" + width="495" + height="120" + id="svg2" + version="1.1" + inkscape:version="0.47 r22583" + sodipodi:docname="pmie_rule6.svg" + inkscape:export-filename="/source/git/nathans/pcp-gui/man/html/images/pmie_rule6.png" + inkscape:export-xdpi="90" + inkscape:export-ydpi="90"> + <defs + id="defs4"> + <inkscape:perspective + sodipodi:type="inkscape:persp3d" + inkscape:vp_x="0 : 526.18109 : 1" + inkscape:vp_y="0 : 1000 : 0" + inkscape:vp_z="744.09448 : 526.18109 : 1" + inkscape:persp3d-origin="372.04724 : 350.78739 : 1" + id="perspective10" /> + <inkscape:perspective + id="perspective4112" + inkscape:persp3d-origin="0.5 : 0.33333333 : 1" + inkscape:vp_z="1 : 0.5 : 1" + inkscape:vp_y="0 : 1000 : 0" + inkscape:vp_x="0 : 0.5 : 1" + sodipodi:type="inkscape:persp3d" /> + <inkscape:perspective + id="perspective4112-1" + inkscape:persp3d-origin="0.5 : 0.33333333 : 1" + inkscape:vp_z="1 : 0.5 : 1" + inkscape:vp_y="0 : 1000 : 0" + inkscape:vp_x="0 : 0.5 : 1" + sodipodi:type="inkscape:persp3d" /> + <inkscape:perspective + id="perspective2853" + inkscape:persp3d-origin="0.5 : 0.33333333 : 1" + inkscape:vp_z="1 : 0.5 : 1" + inkscape:vp_y="0 : 1000 : 0" + inkscape:vp_x="0 : 0.5 : 1" + sodipodi:type="inkscape:persp3d" /> + <inkscape:perspective + id="perspective2853-2" + inkscape:persp3d-origin="0.5 : 0.33333333 : 1" + inkscape:vp_z="1 : 0.5 : 1" + inkscape:vp_y="0 : 1000 : 0" + inkscape:vp_x="0 : 0.5 : 1" + sodipodi:type="inkscape:persp3d" /> + </defs> + <sodipodi:namedview + id="base" + pagecolor="#ffffff" + bordercolor="#666666" + borderopacity="1.0" + inkscape:pageopacity="0.0" + inkscape:pageshadow="2" + inkscape:zoom="0.7" + inkscape:cx="243.73106" + inkscape:cy="133.99048" + inkscape:document-units="px" + inkscape:current-layer="layer1" + showgrid="false" /> + <metadata + id="metadata7"> + <rdf:RDF> + <cc:Work + rdf:about=""> + <dc:format>image/svg+xml</dc:format> + <dc:type + rdf:resource="http://purl.org/dc/dcmitype/StillImage" /> + <dc:title></dc:title> + </cc:Work> + </rdf:RDF> + </metadata> + <g + inkscape:label="Layer 1" + inkscape:groupmode="layer" + id="layer1" + transform="translate(0,-932.36218)"> + <rect + style="fill:#ffffff;fill-opacity:1;fill-rule:nonzero;stroke:#f80824;stroke-width:4.88859749;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" + id="rect3592" + width="467.25424" + height="104.39713" + x="15.658585" + y="940.30652" /> + <text + xml:space="preserve" + style="font-size:24px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;fill:#000000;fill-opacity:1;stroke:none;font-family:FreeSans;-inkscape-font-specification:FreeSans" + x="74.285713" + y="88.571426" + id="text3596" + transform="translate(0,852.36218)"><tspan + sodipodi:role="line" + id="tspan3598" + x="74.285713" + y="88.571426" /></text> + <text + xml:space="preserve" + style="font-size:24px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;fill:#000000;fill-opacity:1;stroke:none;font-family:FreeSans;-inkscape-font-specification:FreeSans" + x="35.142857" + y="969.79077" + id="text3600"><tspan + sodipodi:role="line" + id="tspan3602" + x="35.142857" + y="969.79077" + style="font-weight:bold">30%_inst</tspan><tspan + sodipodi:role="line" + x="35.142857" + y="999.79077" + style="font-weight:bold" + id="tspan2840"> disk.dev.total <tspan + style="font-weight:bold;fill:#ff031d;fill-opacity:1" + id="tspan3606">></tspan> 50 <tspan + style="font-weight:bold;fill:#ff0000;fill-opacity:1" + id="tspan3654">count / sec</tspan></tspan><tspan + sodipodi:role="line" + x="35.142857" + y="1029.7908" + id="tspan3604" + style="font-weight:bold"><tspan + style="font-weight:bold;fill:#ff0000;fill-opacity:1" + id="tspan3656">-> alarm </tspan>"30% of disks are very busy"<tspan + style="font-weight:bold;fill:#ed071b;fill-opacity:1" + id="tspan4086"> ;</tspan></tspan></text> + </g> +</svg> diff --git a/man/html/images/pmtime_archive.png b/man/html/images/pmtime_archive.png Binary files differnew file mode 100644 index 0000000..62ff1d1 --- /dev/null +++ b/man/html/images/pmtime_archive.png diff --git a/man/html/images/pmtime_bounds.png b/man/html/images/pmtime_bounds.png Binary files differnew file mode 100644 index 0000000..5124107 --- /dev/null +++ b/man/html/images/pmtime_bounds.png diff --git a/man/html/images/pmtime_clients.png b/man/html/images/pmtime_clients.png Binary files differnew file mode 100644 index 0000000..e02a9f4 --- /dev/null +++ b/man/html/images/pmtime_clients.png diff --git a/man/html/images/pmtime_live.png b/man/html/images/pmtime_live.png Binary files differnew file mode 100644 index 0000000..d7c3965 --- /dev/null +++ b/man/html/images/pmtime_live.png diff --git a/man/html/images/pmview.flow.png b/man/html/images/pmview.flow.png Binary files differnew file mode 100644 index 0000000..021e9fe --- /dev/null +++ b/man/html/images/pmview.flow.png diff --git a/man/html/images/pmview_buttons.png b/man/html/images/pmview_buttons.png Binary files differnew file mode 100644 index 0000000..400260c --- /dev/null +++ b/man/html/images/pmview_buttons.png diff --git a/man/html/images/rack.jpg b/man/html/images/rack.jpg Binary files differnew file mode 100644 index 0000000..c6dee25 --- /dev/null +++ b/man/html/images/rack.jpg diff --git a/man/html/images/rattle.png b/man/html/images/rattle.png Binary files differnew file mode 100644 index 0000000..e5bebf7 --- /dev/null +++ b/man/html/images/rattle.png diff --git a/man/html/images/sar-d.png b/man/html/images/sar-d.png Binary files differnew file mode 100644 index 0000000..c377b64 --- /dev/null +++ b/man/html/images/sar-d.png diff --git a/man/html/images/server.jpg b/man/html/images/server.jpg Binary files differnew file mode 100644 index 0000000..e459941 --- /dev/null +++ b/man/html/images/server.jpg diff --git a/man/html/images/systemlog-arrival.png b/man/html/images/systemlog-arrival.png Binary files differnew file mode 100644 index 0000000..078df04 --- /dev/null +++ b/man/html/images/systemlog-arrival.png diff --git a/man/html/images/systemlog-events.png b/man/html/images/systemlog-events.png Binary files differnew file mode 100644 index 0000000..7773e7e --- /dev/null +++ b/man/html/images/systemlog-events.png diff --git a/man/html/images/systemlog-throughput.png b/man/html/images/systemlog-throughput.png Binary files differnew file mode 100644 index 0000000..eed22ab --- /dev/null +++ b/man/html/images/systemlog-throughput.png diff --git a/man/html/images/systemlogs.png b/man/html/images/systemlogs.png Binary files differnew file mode 100644 index 0000000..1af84af --- /dev/null +++ b/man/html/images/systemlogs.png diff --git a/man/html/images/systemlogs.svg b/man/html/images/systemlogs.svg new file mode 100644 index 0000000..668f732 --- /dev/null +++ b/man/html/images/systemlogs.svg @@ -0,0 +1,5045 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!-- Created with Inkscape (http://www.inkscape.org/) --> + +<svg + xmlns:osb="http://www.openswatchbook.org/uri/2009/osb" + xmlns:dc="http://purl.org/dc/elements/1.1/" + xmlns:cc="http://creativecommons.org/ns#" + xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" + xmlns:svg="http://www.w3.org/2000/svg" + xmlns="http://www.w3.org/2000/svg" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" + xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" + width="1052.3622" + height="744.09448" + id="svg2" + version="1.1" + inkscape:version="0.48.1 r9760" + sodipodi:docname="systemlogs.svg" + inkscape:export-filename="/source/git/clean-pcp-gui/man/html/images/systemlogs.png" + inkscape:export-xdpi="67.980804" + inkscape:export-ydpi="67.980804"> + <defs + id="defs4"> + <linearGradient + id="linearGradient5789" + osb:paint="solid"> + <stop + style="stop-color:#030000;stop-opacity:1;" + offset="0" + id="stop5791" /> + </linearGradient> + <linearGradient + inkscape:collect="always" + id="linearGradient5330"> + <stop + style="stop-color:#1c2bb1;stop-opacity:1;" + offset="0" + id="stop5332" /> + <stop + style="stop-color:#1c2bb1;stop-opacity:0;" + offset="1" + id="stop5334" /> + </linearGradient> + <linearGradient + inkscape:collect="always" + id="linearGradient3879"> + <stop + style="stop-color:#000000;stop-opacity:1;" + offset="0" + id="stop3881" /> + <stop + style="stop-color:#000000;stop-opacity:0;" + offset="1" + id="stop3883" /> + </linearGradient> + <radialGradient + inkscape:collect="always" + xlink:href="#linearGradient3879" + id="radialGradient3885" + cx="144.28572" + cy="673.07648" + fx="144.28572" + fy="673.07648" + r="115.71429" + gradientTransform="matrix(1,0,0,0.9074074,0,62.321902)" + gradientUnits="userSpaceOnUse" /> + <radialGradient + inkscape:collect="always" + xlink:href="#linearGradient3879-0" + id="radialGradient3885-2" + cx="144.28572" + cy="673.07648" + fx="144.28572" + fy="673.07648" + r="115.71429" + gradientTransform="matrix(1,0,0,0.9074074,0,62.321902)" + gradientUnits="userSpaceOnUse" /> + <linearGradient + inkscape:collect="always" + id="linearGradient3879-0"> + <stop + style="stop-color:#000000;stop-opacity:1;" + offset="0" + id="stop3881-6" /> + <stop + style="stop-color:#000000;stop-opacity:0;" + offset="1" + id="stop3883-1" /> + </linearGradient> + <radialGradient + r="115.71429" + fy="673.07648" + fx="144.28572" + cy="673.07648" + cx="144.28572" + gradientTransform="matrix(1,0,0,0.9074074,0,62.321902)" + gradientUnits="userSpaceOnUse" + id="radialGradient3909" + xlink:href="#linearGradient3879-0" + inkscape:collect="always" /> + <radialGradient + r="115.71429" + fy="673.07648" + fx="144.28572" + cy="673.07648" + cx="144.28572" + gradientTransform="matrix(1,0,0,0.9074074,0,62.321902)" + gradientUnits="userSpaceOnUse" + id="radialGradient3909-5" + xlink:href="#linearGradient3879-0-4" + inkscape:collect="always" /> + <linearGradient + inkscape:collect="always" + id="linearGradient3879-0-4"> + <stop + style="stop-color:#000000;stop-opacity:1;" + offset="0" + id="stop3881-6-7" /> + <stop + style="stop-color:#000000;stop-opacity:0;" + offset="1" + id="stop3883-1-6" /> + </linearGradient> + <radialGradient + r="115.71429" + fy="673.07648" + fx="144.28572" + cy="673.07648" + cx="144.28572" + gradientTransform="matrix(1,0,0,0.9074074,0,62.321902)" + gradientUnits="userSpaceOnUse" + id="radialGradient3943-6" + xlink:href="#linearGradient3879-0-4-9" + inkscape:collect="always" /> + <linearGradient + inkscape:collect="always" + id="linearGradient3879-0-4-9"> + <stop + style="stop-color:#000000;stop-opacity:1;" + offset="0" + id="stop3881-6-7-3" /> + <stop + style="stop-color:#000000;stop-opacity:0;" + offset="1" + id="stop3883-1-6-7" /> + </linearGradient> + <radialGradient + inkscape:collect="always" + xlink:href="#linearGradient3879-2" + id="radialGradient3885-5" + cx="144.28572" + cy="673.07648" + fx="144.28572" + fy="673.07648" + r="115.71429" + gradientTransform="matrix(1,0,0,0.9074074,0,62.321902)" + gradientUnits="userSpaceOnUse" /> + <linearGradient + inkscape:collect="always" + id="linearGradient3879-2"> + <stop + style="stop-color:#000000;stop-opacity:1;" + offset="0" + id="stop3881-5" /> + <stop + style="stop-color:#000000;stop-opacity:0;" + offset="1" + id="stop3883-4" /> + </linearGradient> + <radialGradient + r="6.65625" + fy="13.078408" + fx="15.414371" + cy="13.078408" + cx="15.414371" + gradientTransform="matrix(1.2833801,0.06025566,-0.05462227,1.0163358,-12.151415,-10.809765)" + gradientUnits="userSpaceOnUse" + id="radialGradient3236" + xlink:href="#linearGradient4467" + inkscape:collect="always" /> + <radialGradient + r="8.3085051" + fy="21.817987" + fx="18.240929" + cy="21.817987" + cx="18.240929" + gradientUnits="userSpaceOnUse" + id="radialGradient3234" + xlink:href="#linearGradient4454" + inkscape:collect="always" /> + <radialGradient + r="16.528622" + fy="37.967922" + fx="24.130018" + cy="37.967922" + cx="24.130018" + gradientTransform="matrix(1,0,0,0.237968,0,28.93278)" + gradientUnits="userSpaceOnUse" + id="radialGradient3232" + xlink:href="#linearGradient4487" + inkscape:collect="always" /> + <linearGradient + y2="25.743469" + x2="17.500893" + y1="13.602121" + x1="18.292673" + gradientUnits="userSpaceOnUse" + id="linearGradient3230" + xlink:href="#linearGradient2366" + inkscape:collect="always" /> + <linearGradient + y2="31.0625" + x2="33.21875" + y1="34" + x1="30.65625" + gradientTransform="matrix(0.6140542,0,0,0.6534803,-3.2180769,-5.0231708)" + gradientUnits="userSpaceOnUse" + id="linearGradient3228" + xlink:href="#linearGradient4440" + inkscape:collect="always" /> + <linearGradient + y2="30.557772" + x2="31.335964" + y1="26.580296" + x1="27.366341" + gradientTransform="matrix(0.460106,0,0,0.506067,-0.00937036,-1.247578)" + gradientUnits="userSpaceOnUse" + id="linearGradient3226" + xlink:href="#linearGradient2846" + inkscape:collect="always" /> + <radialGradient + r="16.528622" + fy="37.967922" + fx="24.130018" + cy="37.967922" + cx="24.130018" + gradientTransform="matrix(1,0,0,0.237968,0,28.93278)" + gradientUnits="userSpaceOnUse" + id="radialGradient3224" + xlink:href="#linearGradient4477" + inkscape:collect="always" /> + <linearGradient + gradientTransform="matrix(0.460106,0,0,0.506067,-0.00937036,-1.247578)" + y2="30.557772" + x2="31.335964" + y1="26.580296" + x1="27.366341" + gradientUnits="userSpaceOnUse" + id="linearGradient2432" + xlink:href="#linearGradient2846" + inkscape:collect="always" /> + <linearGradient + y2="31.0625" + x2="33.21875" + y1="34" + x1="30.65625" + gradientTransform="matrix(0.6140542,0,0,0.6534803,-3.2180769,-5.0231708)" + gradientUnits="userSpaceOnUse" + id="linearGradient2428" + xlink:href="#linearGradient4440" + inkscape:collect="always" /> + <radialGradient + r="6.65625" + fy="13.078408" + fx="15.414371" + cy="13.078408" + cx="15.414371" + gradientTransform="matrix(1.2833801,0.06025566,-0.05462227,1.0163358,-12.151415,-10.809765)" + gradientUnits="userSpaceOnUse" + id="radialGradient2421" + xlink:href="#linearGradient4467" + inkscape:collect="always" /> + <radialGradient + inkscape:collect="always" + xlink:href="#linearGradient4477" + id="radialGradient2842" + gradientUnits="userSpaceOnUse" + gradientTransform="matrix(1,0,0,0.237968,0,28.93278)" + cx="24.130018" + cy="37.967922" + fx="24.130018" + fy="37.967922" + r="16.528622" /> + <linearGradient + inkscape:collect="always" + xlink:href="#linearGradient2366" + id="linearGradient2372" + x1="18.292673" + y1="13.602121" + x2="17.500893" + y2="25.743469" + gradientUnits="userSpaceOnUse" /> + <radialGradient + gradientUnits="userSpaceOnUse" + gradientTransform="matrix(1,0,0,0.237968,0,28.93278)" + r="16.528622" + fy="37.967922" + fx="24.130018" + cy="37.967922" + cx="24.130018" + id="radialGradient4493" + xlink:href="#linearGradient4487" + inkscape:collect="always" /> + <radialGradient + gradientUnits="userSpaceOnUse" + r="8.3085051" + fy="21.817987" + fx="18.240929" + cy="21.817987" + cx="18.240929" + id="radialGradient4460" + xlink:href="#linearGradient4454" + inkscape:collect="always" /> + <linearGradient + id="linearGradient4440"> + <stop + id="stop4442" + offset="0" + style="stop-color:#7d7d7d;stop-opacity:1;" /> + <stop + style="stop-color:#b1b1b1;stop-opacity:1.0000000;" + offset="0.50000000" + id="stop4448" /> + <stop + id="stop4444" + offset="1.0000000" + style="stop-color:#686868;stop-opacity:1.0000000;" /> + </linearGradient> + <linearGradient + id="linearGradient4454"> + <stop + id="stop4456" + offset="0" + style="stop-color:#3536e5;stop-opacity:0.20784314;" /> + <stop + id="stop4458" + offset="1.0000000" + style="stop-color:#729fcf;stop-opacity:0.67619050;" /> + </linearGradient> + <linearGradient + id="linearGradient4467"> + <stop + id="stop4469" + offset="0" + style="stop-color:#ffffff;stop-opacity:1;" /> + <stop + id="stop4471" + offset="1.0000000" + style="stop-color:#ffffff;stop-opacity:0.24761905;" /> + </linearGradient> + <linearGradient + id="linearGradient4477" + inkscape:collect="always"> + <stop + id="stop4479" + offset="0" + style="stop-color:#000000;stop-opacity:1;" /> + <stop + id="stop4481" + offset="1" + style="stop-color:#000000;stop-opacity:0;" /> + </linearGradient> + <linearGradient + id="linearGradient4487" + inkscape:collect="always"> + <stop + id="stop4489" + offset="0" + style="stop-color:#ffffff;stop-opacity:1;" /> + <stop + id="stop4491" + offset="1" + style="stop-color:#ffffff;stop-opacity:0;" /> + </linearGradient> + <linearGradient + id="linearGradient2366"> + <stop + style="stop-color:#ffffff;stop-opacity:1;" + offset="0" + id="stop2368" /> + <stop + id="stop2374" + offset="0.50000000" + style="stop-color:#ffffff;stop-opacity:0.21904762;" /> + <stop + style="stop-color:#ffffff;stop-opacity:1.0000000;" + offset="1.0000000" + id="stop2370" /> + </linearGradient> + <linearGradient + id="linearGradient2846"> + <stop + style="stop-color:#3f3535;stop-opacity:1;" + offset="0" + id="stop2848" /> + <stop + style="stop-color:#0f0808;stop-opacity:1;" + offset="1" + id="stop2850" /> + </linearGradient> + <inkscape:perspective + id="perspective47" + inkscape:persp3d-origin="11 : 7.3333333 : 1" + inkscape:vp_z="22 : 11 : 1" + inkscape:vp_y="0 : 1000 : 0" + inkscape:vp_x="0 : 11 : 1" + sodipodi:type="inkscape:persp3d" /> + <radialGradient + r="5.257" + fy="64.567902" + fx="20.892099" + cy="64.567902" + cx="20.892099" + gradientTransform="matrix(0.229703,0,0,0.229703,4.613529,3.979808)" + gradientUnits="userSpaceOnUse" + id="radialGradient3205" + xlink:href="#aigrd3" + inkscape:collect="always" /> + <radialGradient + r="5.256" + fy="114.5684" + fx="20.892099" + cy="114.5684" + cx="20.892099" + gradientTransform="matrix(0.229703,0,0,0.229703,4.613529,3.979808)" + gradientUnits="userSpaceOnUse" + id="radialGradient3203" + xlink:href="#aigrd2" + inkscape:collect="always" /> + <radialGradient + r="38.158695" + fy="7.2678967" + fx="8.1435566" + cy="7.2678967" + cx="8.1435566" + gradientTransform="matrix(0.968273,0,0,1.032767,3.353553,0.646447)" + gradientUnits="userSpaceOnUse" + id="radialGradient3201" + xlink:href="#linearGradient15662" + inkscape:collect="always" /> + <radialGradient + r="37.751713" + fy="3.7561285" + fx="8.824419" + cy="3.7561285" + cx="8.824419" + gradientTransform="matrix(0.968273,0,0,1.032767,3.353553,0.646447)" + gradientUnits="userSpaceOnUse" + id="radialGradient3199" + xlink:href="#linearGradient269" + inkscape:collect="always" /> + <radialGradient + r="86.70845" + fy="35.736916" + fx="33.966679" + cy="35.736916" + cx="33.966679" + gradientTransform="scale(0.960493,1.041132)" + gradientUnits="userSpaceOnUse" + id="radialGradient3197" + xlink:href="#linearGradient259" + inkscape:collect="always" /> + <radialGradient + r="15.821514" + fy="42.07798" + fx="24.306795" + cy="42.07798" + cx="24.306795" + gradientTransform="matrix(1,0,0,0.284916,0,30.08928)" + gradientUnits="userSpaceOnUse" + id="radialGradient3195" + xlink:href="#linearGradient4542" + inkscape:collect="always" /> + <linearGradient + id="linearGradient259"> + <stop + style="stop-color:#fafafa;stop-opacity:1.0000000;" + offset="0.0000000" + id="stop260" /> + <stop + style="stop-color:#bbbbbb;stop-opacity:1.0000000;" + offset="1.0000000" + id="stop261" /> + </linearGradient> + <linearGradient + id="linearGradient269"> + <stop + style="stop-color:#a3a3a3;stop-opacity:1.0000000;" + offset="0.0000000" + id="stop270" /> + <stop + style="stop-color:#4c4c4c;stop-opacity:1.0000000;" + offset="1.0000000" + id="stop271" /> + </linearGradient> + <radialGradient + gradientUnits="userSpaceOnUse" + fy="114.5684" + fx="20.892099" + r="5.256" + cy="114.5684" + cx="20.892099" + id="aigrd2"> + <stop + id="stop15566" + style="stop-color:#F0F0F0" + offset="0" /> + <stop + id="stop15568" + style="stop-color:#9a9a9a;stop-opacity:1.0000000;" + offset="1.0000000" /> + </radialGradient> + <radialGradient + gradientUnits="userSpaceOnUse" + fy="64.567902" + fx="20.892099" + r="5.257" + cy="64.567902" + cx="20.892099" + id="aigrd3"> + <stop + id="stop15573" + style="stop-color:#F0F0F0" + offset="0" /> + <stop + id="stop15575" + style="stop-color:#9a9a9a;stop-opacity:1.0000000;" + offset="1.0000000" /> + </radialGradient> + <linearGradient + id="linearGradient15662"> + <stop + style="stop-color:#ffffff;stop-opacity:1.0000000;" + offset="0.0000000" + id="stop15664" /> + <stop + style="stop-color:#f8f8f8;stop-opacity:1.0000000;" + offset="1.0000000" + id="stop15666" /> + </linearGradient> + <linearGradient + id="linearGradient4542" + inkscape:collect="always"> + <stop + id="stop4544" + offset="0" + style="stop-color:#000000;stop-opacity:1;" /> + <stop + id="stop4546" + offset="1" + style="stop-color:#000000;stop-opacity:0;" /> + </linearGradient> + <radialGradient + r="15.821514" + fy="42.07798" + fx="24.306795" + cy="42.07798" + cx="24.306795" + gradientTransform="matrix(1,0,0,0.284916,0,30.08928)" + gradientUnits="userSpaceOnUse" + id="radialGradient3195-8" + xlink:href="#linearGradient4542-6" + inkscape:collect="always" /> + <linearGradient + id="linearGradient4542-6" + inkscape:collect="always"> + <stop + id="stop4544-8" + offset="0" + style="stop-color:#000000;stop-opacity:1;" /> + <stop + id="stop4546-8" + offset="1" + style="stop-color:#000000;stop-opacity:0;" /> + </linearGradient> + <radialGradient + r="86.70845" + fy="35.736916" + fx="33.966679" + cy="35.736916" + cx="33.966679" + gradientTransform="scale(0.960493,1.041132)" + gradientUnits="userSpaceOnUse" + id="radialGradient3197-4" + xlink:href="#linearGradient259-3" + inkscape:collect="always" /> + <linearGradient + id="linearGradient259-3"> + <stop + style="stop-color:#fafafa;stop-opacity:1.0000000;" + offset="0.0000000" + id="stop260-1" /> + <stop + style="stop-color:#bbbbbb;stop-opacity:1.0000000;" + offset="1.0000000" + id="stop261-4" /> + </linearGradient> + <radialGradient + r="37.751713" + fy="3.7561285" + fx="8.824419" + cy="3.7561285" + cx="8.824419" + gradientTransform="matrix(0.968273,0,0,1.032767,3.353553,0.646447)" + gradientUnits="userSpaceOnUse" + id="radialGradient3199-9" + xlink:href="#linearGradient269-2" + inkscape:collect="always" /> + <linearGradient + id="linearGradient269-2"> + <stop + style="stop-color:#a3a3a3;stop-opacity:1.0000000;" + offset="0.0000000" + id="stop270-0" /> + <stop + style="stop-color:#4c4c4c;stop-opacity:1.0000000;" + offset="1.0000000" + id="stop271-6" /> + </linearGradient> + <radialGradient + r="38.158695" + fy="7.2678967" + fx="8.1435566" + cy="7.2678967" + cx="8.1435566" + gradientTransform="matrix(0.968273,0,0,1.032767,3.353553,0.646447)" + gradientUnits="userSpaceOnUse" + id="radialGradient3201-8" + xlink:href="#linearGradient15662-9" + inkscape:collect="always" /> + <linearGradient + id="linearGradient15662-9"> + <stop + style="stop-color:#ffffff;stop-opacity:1.0000000;" + offset="0.0000000" + id="stop15664-2" /> + <stop + style="stop-color:#f8f8f8;stop-opacity:1.0000000;" + offset="1.0000000" + id="stop15666-6" /> + </linearGradient> + <radialGradient + r="5.256" + fy="114.5684" + fx="20.892099" + cy="114.5684" + cx="20.892099" + gradientTransform="matrix(0.229703,0,0,0.229703,4.613529,3.979808)" + gradientUnits="userSpaceOnUse" + id="radialGradient3203-6" + xlink:href="#aigrd2-4" + inkscape:collect="always" /> + <radialGradient + gradientUnits="userSpaceOnUse" + fy="114.5684" + fx="20.892099" + r="5.256" + cy="114.5684" + cx="20.892099" + id="aigrd2-4"> + <stop + id="stop15566-9" + style="stop-color:#F0F0F0" + offset="0" /> + <stop + id="stop15568-5" + style="stop-color:#9a9a9a;stop-opacity:1.0000000;" + offset="1.0000000" /> + </radialGradient> + <radialGradient + r="5.257" + fy="64.567902" + fx="20.892099" + cy="64.567902" + cx="20.892099" + gradientTransform="matrix(0.229703,0,0,0.229703,4.613529,3.979808)" + gradientUnits="userSpaceOnUse" + id="radialGradient3205-0" + xlink:href="#aigrd3-4" + inkscape:collect="always" /> + <radialGradient + gradientUnits="userSpaceOnUse" + fy="64.567902" + fx="20.892099" + r="5.257" + cy="64.567902" + cx="20.892099" + id="aigrd3-4"> + <stop + id="stop15573-8" + style="stop-color:#F0F0F0" + offset="0" /> + <stop + id="stop15575-7" + style="stop-color:#9a9a9a;stop-opacity:1.0000000;" + offset="1.0000000" /> + </radialGradient> + <radialGradient + r="15.821514" + fy="42.07798" + fx="24.306795" + cy="42.07798" + cx="24.306795" + gradientTransform="matrix(1,0,0,0.284916,0,30.08928)" + gradientUnits="userSpaceOnUse" + id="radialGradient3195-8-2" + xlink:href="#linearGradient4542-6-9" + inkscape:collect="always" /> + <linearGradient + id="linearGradient4542-6-9" + inkscape:collect="always"> + <stop + id="stop4544-8-3" + offset="0" + style="stop-color:#000000;stop-opacity:1;" /> + <stop + id="stop4546-8-9" + offset="1" + style="stop-color:#000000;stop-opacity:0;" /> + </linearGradient> + <radialGradient + r="86.70845" + fy="35.736916" + fx="33.966679" + cy="35.736916" + cx="33.966679" + gradientTransform="scale(0.960493,1.041132)" + gradientUnits="userSpaceOnUse" + id="radialGradient3197-4-0" + xlink:href="#linearGradient259-3-8" + inkscape:collect="always" /> + <linearGradient + id="linearGradient259-3-8"> + <stop + style="stop-color:#fafafa;stop-opacity:1.0000000;" + offset="0.0000000" + id="stop260-1-8" /> + <stop + style="stop-color:#bbbbbb;stop-opacity:1.0000000;" + offset="1.0000000" + id="stop261-4-5" /> + </linearGradient> + <radialGradient + r="37.751713" + fy="3.7561285" + fx="8.824419" + cy="3.7561285" + cx="8.824419" + gradientTransform="matrix(0.968273,0,0,1.032767,3.353553,0.646447)" + gradientUnits="userSpaceOnUse" + id="radialGradient3199-9-0" + xlink:href="#linearGradient269-2-9" + inkscape:collect="always" /> + <linearGradient + id="linearGradient269-2-9"> + <stop + style="stop-color:#a3a3a3;stop-opacity:1.0000000;" + offset="0.0000000" + id="stop270-0-6" /> + <stop + style="stop-color:#4c4c4c;stop-opacity:1.0000000;" + offset="1.0000000" + id="stop271-6-3" /> + </linearGradient> + <radialGradient + r="38.158695" + fy="7.2678967" + fx="8.1435566" + cy="7.2678967" + cx="8.1435566" + gradientTransform="matrix(0.968273,0,0,1.032767,3.353553,0.646447)" + gradientUnits="userSpaceOnUse" + id="radialGradient3201-8-8" + xlink:href="#linearGradient15662-9-5" + inkscape:collect="always" /> + <linearGradient + id="linearGradient15662-9-5"> + <stop + style="stop-color:#ffffff;stop-opacity:1.0000000;" + offset="0.0000000" + id="stop15664-2-6" /> + <stop + style="stop-color:#f8f8f8;stop-opacity:1.0000000;" + offset="1.0000000" + id="stop15666-6-1" /> + </linearGradient> + <radialGradient + r="5.256" + fy="114.5684" + fx="20.892099" + cy="114.5684" + cx="20.892099" + gradientTransform="matrix(0.229703,0,0,0.229703,4.613529,3.979808)" + gradientUnits="userSpaceOnUse" + id="radialGradient3203-6-1" + xlink:href="#aigrd2-4-5" + inkscape:collect="always" /> + <radialGradient + gradientUnits="userSpaceOnUse" + fy="114.5684" + fx="20.892099" + r="5.256" + cy="114.5684" + cx="20.892099" + id="aigrd2-4-5"> + <stop + id="stop15566-9-9" + style="stop-color:#F0F0F0" + offset="0" /> + <stop + id="stop15568-5-8" + style="stop-color:#9a9a9a;stop-opacity:1.0000000;" + offset="1.0000000" /> + </radialGradient> + <radialGradient + r="5.257" + fy="64.567902" + fx="20.892099" + cy="64.567902" + cx="20.892099" + gradientTransform="matrix(0.229703,0,0,0.229703,4.613529,3.979808)" + gradientUnits="userSpaceOnUse" + id="radialGradient3205-0-4" + xlink:href="#aigrd3-4-8" + inkscape:collect="always" /> + <radialGradient + gradientUnits="userSpaceOnUse" + fy="64.567902" + fx="20.892099" + r="5.257" + cy="64.567902" + cx="20.892099" + id="aigrd3-4-8"> + <stop + id="stop15573-8-1" + style="stop-color:#F0F0F0" + offset="0" /> + <stop + id="stop15575-7-0" + style="stop-color:#9a9a9a;stop-opacity:1.0000000;" + offset="1.0000000" /> + </radialGradient> + <radialGradient + r="15.821514" + fy="42.07798" + fx="24.306795" + cy="42.07798" + cx="24.306795" + gradientTransform="matrix(1,0,0,0.284916,0,30.08928)" + gradientUnits="userSpaceOnUse" + id="radialGradient3195-8-2-3" + xlink:href="#linearGradient4542-6-9-3" + inkscape:collect="always" /> + <linearGradient + id="linearGradient4542-6-9-3" + inkscape:collect="always"> + <stop + id="stop4544-8-3-8" + offset="0" + style="stop-color:#000000;stop-opacity:1;" /> + <stop + id="stop4546-8-9-6" + offset="1" + style="stop-color:#000000;stop-opacity:0;" /> + </linearGradient> + <radialGradient + r="86.70845" + fy="35.736916" + fx="33.966679" + cy="35.736916" + cx="33.966679" + gradientTransform="scale(0.960493,1.041132)" + gradientUnits="userSpaceOnUse" + id="radialGradient3197-4-0-0" + xlink:href="#linearGradient259-3-8-4" + inkscape:collect="always" /> + <linearGradient + id="linearGradient259-3-8-4"> + <stop + style="stop-color:#fafafa;stop-opacity:1.0000000;" + offset="0.0000000" + id="stop260-1-8-8" /> + <stop + style="stop-color:#bbbbbb;stop-opacity:1.0000000;" + offset="1.0000000" + id="stop261-4-5-8" /> + </linearGradient> + <radialGradient + r="37.751713" + fy="3.7561285" + fx="8.824419" + cy="3.7561285" + cx="8.824419" + gradientTransform="matrix(0.968273,0,0,1.032767,3.353553,0.646447)" + gradientUnits="userSpaceOnUse" + id="radialGradient3199-9-0-8" + xlink:href="#linearGradient269-2-9-9" + inkscape:collect="always" /> + <linearGradient + id="linearGradient269-2-9-9"> + <stop + style="stop-color:#a3a3a3;stop-opacity:1.0000000;" + offset="0.0000000" + id="stop270-0-6-7" /> + <stop + style="stop-color:#4c4c4c;stop-opacity:1.0000000;" + offset="1.0000000" + id="stop271-6-3-7" /> + </linearGradient> + <radialGradient + r="38.158695" + fy="7.2678967" + fx="8.1435566" + cy="7.2678967" + cx="8.1435566" + gradientTransform="matrix(0.968273,0,0,1.032767,3.353553,0.646447)" + gradientUnits="userSpaceOnUse" + id="radialGradient3201-8-8-6" + xlink:href="#linearGradient15662-9-5-4" + inkscape:collect="always" /> + <linearGradient + id="linearGradient15662-9-5-4"> + <stop + style="stop-color:#ffffff;stop-opacity:1.0000000;" + offset="0.0000000" + id="stop15664-2-6-3" /> + <stop + style="stop-color:#f8f8f8;stop-opacity:1.0000000;" + offset="1.0000000" + id="stop15666-6-1-0" /> + </linearGradient> + <radialGradient + r="5.256" + fy="114.5684" + fx="20.892099" + cy="114.5684" + cx="20.892099" + gradientTransform="matrix(0.229703,0,0,0.229703,4.613529,3.979808)" + gradientUnits="userSpaceOnUse" + id="radialGradient3203-6-1-3" + xlink:href="#aigrd2-4-5-0" + inkscape:collect="always" /> + <radialGradient + gradientUnits="userSpaceOnUse" + fy="114.5684" + fx="20.892099" + r="5.256" + cy="114.5684" + cx="20.892099" + id="aigrd2-4-5-0"> + <stop + id="stop15566-9-9-9" + style="stop-color:#F0F0F0" + offset="0" /> + <stop + id="stop15568-5-8-2" + style="stop-color:#9a9a9a;stop-opacity:1.0000000;" + offset="1.0000000" /> + </radialGradient> + <radialGradient + r="5.257" + fy="64.567902" + fx="20.892099" + cy="64.567902" + cx="20.892099" + gradientTransform="matrix(0.229703,0,0,0.229703,4.613529,3.979808)" + gradientUnits="userSpaceOnUse" + id="radialGradient3205-0-4-5" + xlink:href="#aigrd3-4-8-4" + inkscape:collect="always" /> + <radialGradient + gradientUnits="userSpaceOnUse" + fy="64.567902" + fx="20.892099" + r="5.257" + cy="64.567902" + cx="20.892099" + id="aigrd3-4-8-4"> + <stop + id="stop15573-8-1-0" + style="stop-color:#F0F0F0" + offset="0" /> + <stop + id="stop15575-7-0-5" + style="stop-color:#9a9a9a;stop-opacity:1.0000000;" + offset="1.0000000" /> + </radialGradient> + <linearGradient + id="linearGradient259-3-8-40"> + <stop + style="stop-color:#fafafa;stop-opacity:1.0000000;" + offset="0.0000000" + id="stop260-1-8-6" /> + <stop + style="stop-color:#bbbbbb;stop-opacity:1.0000000;" + offset="1.0000000" + id="stop261-4-5-2" /> + </linearGradient> + <linearGradient + id="linearGradient269-2-9-90"> + <stop + style="stop-color:#a3a3a3;stop-opacity:1.0000000;" + offset="0.0000000" + id="stop270-0-6-8" /> + <stop + style="stop-color:#4c4c4c;stop-opacity:1.0000000;" + offset="1.0000000" + id="stop271-6-3-1" /> + </linearGradient> + <linearGradient + id="linearGradient15662-9-5-1"> + <stop + style="stop-color:#ffffff;stop-opacity:1.0000000;" + offset="0.0000000" + id="stop15664-2-6-1" /> + <stop + style="stop-color:#f8f8f8;stop-opacity:1.0000000;" + offset="1.0000000" + id="stop15666-6-1-03" /> + </linearGradient> + <radialGradient + gradientUnits="userSpaceOnUse" + fy="114.5684" + fx="20.892099" + r="5.256" + cy="114.5684" + cx="20.892099" + id="aigrd2-4-5-03"> + <stop + id="stop15566-9-9-91" + style="stop-color:#F0F0F0" + offset="0" /> + <stop + id="stop15568-5-8-9" + style="stop-color:#9a9a9a;stop-opacity:1.0000000;" + offset="1.0000000" /> + </radialGradient> + <radialGradient + gradientUnits="userSpaceOnUse" + fy="64.567902" + fx="20.892099" + r="5.257" + cy="64.567902" + cx="20.892099" + id="aigrd3-4-8-9"> + <stop + id="stop15573-8-1-3" + style="stop-color:#F0F0F0" + offset="0" /> + <stop + id="stop15575-7-0-3" + style="stop-color:#9a9a9a;stop-opacity:1.0000000;" + offset="1.0000000" /> + </radialGradient> + <radialGradient + inkscape:collect="always" + xlink:href="#linearGradient5330" + id="radialGradient5336" + cx="144.28572" + cy="673.07648" + fx="144.28572" + fy="673.07648" + r="115.71429" + gradientTransform="matrix(1,0,0,0.9074074,0,62.321902)" + gradientUnits="userSpaceOnUse" /> + <radialGradient + inkscape:collect="always" + xlink:href="#linearGradient3879-0-4" + id="radialGradient5519" + gradientUnits="userSpaceOnUse" + gradientTransform="matrix(1,0,0,0.9074074,0,62.321902)" + cx="144.28572" + cy="673.07648" + fx="144.28572" + fy="673.07648" + r="115.71429" /> + <linearGradient + y2="458.22222" + x2="-31.20402" + y1="511.62514" + x1="64.41948" + id="linearGradient854" + xlink:href="#linearGradient912" + gradientTransform="matrix(1.1228801,7.338931,4.6856018,-0.54366125,170.51026,417.75572)" + gradientUnits="userSpaceOnUse" /> + <radialGradient + id="radialGradient915" + xlink:href="#linearGradient912" /> + <linearGradient + id="linearGradient912"> + <stop + id="stop913" + offset="0.0000000" + style="stop-color:#f3f3f3;stop-opacity:1.0000000;" /> + <stop + id="stop855" + offset="0.37650406" + style="stop-color:#ffffff;stop-opacity:1.0000000;" /> + <stop + id="stop914" + offset="1.0000000" + style="stop-color:#e6ffff;stop-opacity:1.0000000;" /> + </linearGradient> + <radialGradient + inkscape:collect="always" + xlink:href="#linearGradient5330" + id="radialGradient6332" + gradientUnits="userSpaceOnUse" + gradientTransform="matrix(1,0,0,0.9074074,0,62.321902)" + cx="144.28572" + cy="673.07648" + fx="144.28572" + fy="673.07648" + r="115.71429" /> + <linearGradient + y2="458.22223" + x2="-31.20402" + y1="511.62515" + x1="64.419479" + id="linearGradient854-5" + xlink:href="#linearGradient912-6" + gradientTransform="matrix(1.1228801,7.338931,4.6856018,-0.54366125,178.51026,417.75572)" + gradientUnits="userSpaceOnUse" /> + <linearGradient + id="linearGradient912-6"> + <stop + id="stop913-2" + offset="0.0000000" + style="stop-color:#f3f3f3;stop-opacity:1.0000000;" /> + <stop + id="stop855-5" + offset="0.37650406" + style="stop-color:#ffffff;stop-opacity:1.0000000;" /> + <stop + id="stop914-9" + offset="1.0000000" + style="stop-color:#e6ffff;stop-opacity:1.0000000;" /> + </linearGradient> + <filter + inkscape:collect="always" + id="filter6431" + x="-0.12220462" + width="1.2444092" + y="-0.079324303" + height="1.1586486"> + <feGaussianBlur + inkscape:collect="always" + stdDeviation="17.002565" + id="feGaussianBlur6433" /> + </filter> + <linearGradient + y2="3.8451097" + x2="35.520542" + y1="3.9384086" + x1="34.300991" + gradientUnits="userSpaceOnUse" + id="linearGradient2045" + xlink:href="#linearGradient2711" + inkscape:collect="always" /> + <linearGradient + y2="3.8451097" + x2="35.520542" + y1="3.9384086" + x1="34.300991" + gradientUnits="userSpaceOnUse" + id="linearGradient2043" + xlink:href="#linearGradient2711" + inkscape:collect="always" /> + <linearGradient + y2="3.8451097" + x2="35.520542" + y1="3.9384086" + x1="34.300991" + gradientUnits="userSpaceOnUse" + id="linearGradient2041" + xlink:href="#linearGradient2711" + inkscape:collect="always" /> + <linearGradient + y2="3.8451097" + x2="35.520542" + y1="3.9384086" + x1="34.300991" + gradientUnits="userSpaceOnUse" + id="linearGradient2039" + xlink:href="#linearGradient2711" + inkscape:collect="always" /> + <linearGradient + y2="3.8451097" + x2="35.520542" + y1="3.9384086" + x1="34.300991" + gradientUnits="userSpaceOnUse" + id="linearGradient2037" + xlink:href="#linearGradient2711" + inkscape:collect="always" /> + <linearGradient + y2="74.098007" + x2="8.6485014" + y1="101.2846" + x1="13.62871" + gradientTransform="matrix(2.143634,0,0,0.466498,1,-0.508826)" + gradientUnits="userSpaceOnUse" + id="linearGradient2035" + xlink:href="#linearGradient2635" + inkscape:collect="always" /> + <linearGradient + y2="100.20015" + x2="8.1134233" + y1="88.509071" + x1="8.1134243" + gradientTransform="scale(2.309851,0.432928)" + gradientUnits="userSpaceOnUse" + id="linearGradient2033" + xlink:href="#linearGradient2752" + inkscape:collect="always" /> + <linearGradient + y2="100.20015" + x2="8.1134233" + y1="88.509071" + x1="8.1134243" + gradientTransform="scale(2.309851,0.432928)" + gradientUnits="userSpaceOnUse" + id="linearGradient2031" + xlink:href="#linearGradient2752" + inkscape:collect="always" /> + <linearGradient + y2="100.20015" + x2="8.1134233" + y1="88.509071" + x1="8.1134243" + gradientTransform="scale(2.309851,0.432928)" + gradientUnits="userSpaceOnUse" + id="linearGradient2029" + xlink:href="#linearGradient2752" + inkscape:collect="always" /> + <linearGradient + y2="31.246054" + x2="32.536823" + y1="5.3817744" + x1="10.390738" + gradientTransform="scale(1.104397,0.905471)" + gradientUnits="userSpaceOnUse" + id="linearGradient2027" + xlink:href="#linearGradient2253" + inkscape:collect="always" /> + <linearGradient + y2="52.536461" + x2="18.176752" + y1="48.643234" + x1="18.316999" + gradientTransform="scale(1.129863,0.885063)" + gradientUnits="userSpaceOnUse" + id="linearGradient2025" + xlink:href="#linearGradient2245" + inkscape:collect="always" /> + <radialGradient + r="8.7662792" + fy="67.501709" + fx="12.57571" + cy="67.501709" + cx="12.57571" + gradientTransform="scale(1.925808,0.519262)" + gradientUnits="userSpaceOnUse" + id="radialGradient2023" + xlink:href="#linearGradient2454" + inkscape:collect="always" /> + <linearGradient + y2="26.729263" + x2="17.199417" + y1="1.6537577" + x1="11.492236" + gradientTransform="matrix(1.238977,0,0,0.895955,0.590553,-1.331524)" + gradientUnits="userSpaceOnUse" + id="linearGradient2021" + xlink:href="#linearGradient2667" + inkscape:collect="always" /> + <linearGradient + y2="55.200756" + x2="34.974548" + y1="13.004725" + x1="17.698339" + gradientTransform="matrix(1.108069,0,0,0.902471,1,1)" + gradientUnits="userSpaceOnUse" + id="linearGradient2019" + xlink:href="#linearGradient2415" + inkscape:collect="always" /> + <linearGradient + y2="162.45061" + x2="3.7069974" + y1="171.29134" + x1="3.7069976" + gradientTransform="matrix(5.705159,0,0,0.17528,1,-0.679373)" + gradientUnits="userSpaceOnUse" + id="linearGradient2017" + xlink:href="#linearGradient2683" + inkscape:collect="always" /> + <linearGradient + y2="8.8666229" + x2="16.315819" + y1="32.622238" + x1="19.150396" + gradientTransform="matrix(1.174139,0,0,0.945431,0.721825,-1.331524)" + gradientUnits="userSpaceOnUse" + id="linearGradient2015" + xlink:href="#linearGradient2675" + inkscape:collect="always" /> + <linearGradient + y2="31.246054" + x2="32.536823" + y1="5.3817744" + x1="10.390738" + gradientTransform="scale(1.104397,0.905471)" + gradientUnits="userSpaceOnUse" + id="linearGradient2013" + xlink:href="#linearGradient2253" + inkscape:collect="always" /> + <linearGradient + y2="33.339787" + x2="34.784473" + y1="7.2293582" + x1="8.6116238" + gradientTransform="matrix(1.129863,0,0,0.885063,-1.625,-1.304372)" + gradientUnits="userSpaceOnUse" + id="linearGradient2011" + xlink:href="#linearGradient2245" + inkscape:collect="always" /> + <linearGradient + y2="64.892525" + x2="12.127711" + y1="53.535141" + x1="12.206709" + gradientTransform="scale(1.816345,0.550556)" + gradientUnits="userSpaceOnUse" + id="linearGradient2009" + xlink:href="#linearGradient2701" + inkscape:collect="always" /> + <radialGradient + r="8.7662792" + fy="67.501709" + fx="12.57571" + cy="67.501709" + cx="12.57571" + gradientTransform="scale(1.925808,0.519262)" + gradientUnits="userSpaceOnUse" + id="radialGradient2007" + xlink:href="#linearGradient2454" + inkscape:collect="always" /> + <linearGradient + y2="44.878883" + x2="-23.8857" + y1="49.953003" + x1="-23.8857" + gradientTransform="scale(1.492875,0.669848)" + gradientUnits="userSpaceOnUse" + id="linearGradient2005" + xlink:href="#linearGradient2985" + inkscape:collect="always" /> + <radialGradient + r="8.7662792" + fy="67.501709" + fx="12.57571" + cy="67.501709" + cx="12.57571" + gradientTransform="scale(1.925808,0.519262)" + gradientUnits="userSpaceOnUse" + id="radialGradient2003" + xlink:href="#linearGradient2454" + inkscape:collect="always" /> + <linearGradient + inkscape:collect="always" + xlink:href="#linearGradient2253" + id="linearGradient1413" + gradientUnits="userSpaceOnUse" + gradientTransform="scale(1.104397,0.905471)" + x1="10.390738" + y1="5.3817744" + x2="32.536823" + y2="31.246054" /> + <linearGradient + inkscape:collect="always" + xlink:href="#linearGradient2752" + id="linearGradient1411" + gradientUnits="userSpaceOnUse" + gradientTransform="scale(2.309851,0.432928)" + x1="8.1134243" + y1="88.509071" + x2="8.1134233" + y2="100.20015" /> + <linearGradient + inkscape:collect="always" + xlink:href="#linearGradient2752" + id="linearGradient1409" + gradientUnits="userSpaceOnUse" + gradientTransform="scale(2.309851,0.432928)" + x1="8.1134243" + y1="88.509071" + x2="8.1134233" + y2="100.20015" /> + <linearGradient + inkscape:collect="always" + xlink:href="#linearGradient2985" + id="linearGradient2991" + gradientTransform="scale(1.492875,0.669848)" + x1="-23.8857" + y1="49.953003" + x2="-23.8857" + y2="44.878883" + gradientUnits="userSpaceOnUse" /> + <linearGradient + inkscape:collect="always" + xlink:href="#linearGradient2245" + id="linearGradient2981" + gradientUnits="userSpaceOnUse" + gradientTransform="scale(1.129863,0.885063)" + x1="18.316999" + y1="48.643234" + x2="18.176752" + y2="52.536461" /> + <linearGradient + inkscape:collect="always" + xlink:href="#linearGradient2253" + id="linearGradient2979" + gradientTransform="scale(1.104397,0.905471)" + x1="10.390738" + y1="5.3817744" + x2="32.536823" + y2="31.246054" + gradientUnits="userSpaceOnUse" /> + <linearGradient + inkscape:collect="always" + xlink:href="#linearGradient2752" + id="linearGradient2758" + gradientTransform="scale(2.309851,0.432928)" + x1="8.1134243" + y1="88.509071" + x2="8.1134233" + y2="100.20015" + gradientUnits="userSpaceOnUse" /> + <linearGradient + inkscape:collect="always" + xlink:href="#linearGradient2635" + id="linearGradient2741" + gradientUnits="userSpaceOnUse" + gradientTransform="matrix(2.143634,0,0,0.466498,1,-0.508826)" + x1="13.62871" + y1="101.2846" + x2="8.6485014" + y2="74.098007" /> + <linearGradient + inkscape:collect="always" + xlink:href="#linearGradient2711" + id="linearGradient2733" + gradientUnits="userSpaceOnUse" + x1="34.300991" + y1="3.9384086" + x2="35.520542" + y2="3.8451097" /> + <linearGradient + inkscape:collect="always" + xlink:href="#linearGradient2711" + id="linearGradient2729" + gradientUnits="userSpaceOnUse" + x1="34.300991" + y1="3.9384086" + x2="35.520542" + y2="3.8451097" /> + <linearGradient + inkscape:collect="always" + xlink:href="#linearGradient2711" + id="linearGradient2725" + gradientUnits="userSpaceOnUse" + x1="34.300991" + y1="3.9384086" + x2="35.520542" + y2="3.8451097" /> + <linearGradient + inkscape:collect="always" + xlink:href="#linearGradient2711" + id="linearGradient2721" + gradientUnits="userSpaceOnUse" + x1="34.300991" + y1="3.9384086" + x2="35.520542" + y2="3.8451097" /> + <linearGradient + inkscape:collect="always" + xlink:href="#linearGradient2711" + id="linearGradient2717" + x1="34.300991" + y1="3.9384086" + x2="35.520542" + y2="3.8451097" + gradientUnits="userSpaceOnUse" /> + <linearGradient + inkscape:collect="always" + xlink:href="#linearGradient2701" + id="linearGradient2707" + gradientTransform="scale(1.816345,0.550556)" + x1="12.206709" + y1="53.535141" + x2="12.127711" + y2="64.892525" + gradientUnits="userSpaceOnUse" /> + <linearGradient + inkscape:collect="always" + xlink:href="#linearGradient2683" + id="linearGradient2689" + gradientTransform="matrix(5.705159,0,0,0.17528,1,-0.679373)" + x1="3.7069976" + y1="171.29134" + x2="3.7069974" + y2="162.45061" + gradientUnits="userSpaceOnUse" /> + <linearGradient + inkscape:collect="always" + xlink:href="#linearGradient2675" + id="linearGradient2681" + gradientTransform="matrix(1.174139,0,0,0.945431,0.721825,-1.331524)" + x1="19.150396" + y1="32.622238" + x2="16.315819" + y2="8.8666229" + gradientUnits="userSpaceOnUse" /> + <linearGradient + inkscape:collect="always" + xlink:href="#linearGradient2667" + id="linearGradient2673" + gradientTransform="matrix(1.238977,0,0,0.895955,0.590553,-1.331524)" + x1="11.492236" + y1="1.6537577" + x2="17.199417" + y2="26.729263" + gradientUnits="userSpaceOnUse" /> + <radialGradient + inkscape:collect="always" + xlink:href="#linearGradient2454" + id="radialGradient2659" + gradientUnits="userSpaceOnUse" + gradientTransform="scale(1.925808,0.519262)" + cx="12.57571" + cy="67.501709" + fx="12.57571" + fy="67.501709" + r="8.7662792" /> + <linearGradient + inkscape:collect="always" + xlink:href="#linearGradient2635" + id="linearGradient2655" + gradientUnits="userSpaceOnUse" + gradientTransform="scale(2.143634,0.466498)" + x1="13.62871" + y1="101.2846" + x2="8.6485014" + y2="74.098007" /> + <linearGradient + inkscape:collect="always" + xlink:href="#linearGradient2623" + id="linearGradient2653" + gradientUnits="userSpaceOnUse" + gradientTransform="scale(1.983556,0.504145)" + x1="10.728384" + y1="84.029198" + x2="10.728384" + y2="92.57093" /> + <radialGradient + r="8.7662792" + fy="67.501709" + fx="12.57571" + cy="67.501709" + cx="12.57571" + gradientTransform="scale(1.925808,0.519262)" + gradientUnits="userSpaceOnUse" + id="radialGradient2464" + xlink:href="#linearGradient2454" + inkscape:collect="always" /> + <radialGradient + gradientUnits="userSpaceOnUse" + r="8.7662792" + fy="67.501709" + fx="12.57571" + cy="67.501709" + cx="12.57571" + gradientTransform="scale(1.925808,0.519262)" + id="radialGradient2460" + xlink:href="#linearGradient2454" + inkscape:collect="always" /> + <linearGradient + y2="-1.3221773" + x2="19.994572" + y1="30.078255" + x1="21.356108" + gradientTransform="matrix(1.02787,0,0,0.822296,1.523986,1.001198)" + gradientUnits="userSpaceOnUse" + id="linearGradient2445" + xlink:href="#linearGradient2379" + inkscape:collect="always" /> + <linearGradient + gradientUnits="userSpaceOnUse" + y2="55.200756" + x2="34.974548" + y1="13.004725" + x1="17.698339" + gradientTransform="matrix(1.108069,0,0,0.902471,1,1)" + id="linearGradient2421" + xlink:href="#linearGradient2415" + inkscape:collect="always" /> + <linearGradient + gradientUnits="userSpaceOnUse" + y2="39.03191" + x2="27.289009" + y1="10.842293" + x1="16.119127" + gradientTransform="matrix(1.289166,0,0,0.922731,-0.789284,-0.50338)" + id="linearGradient2334" + xlink:href="#linearGradient2328" + inkscape:collect="always" /> + <linearGradient + gradientUnits="userSpaceOnUse" + y2="53.734985" + x2="24.418941" + y1="9.323514" + x1="16.851954" + gradientTransform="matrix(1.208393,0,0,0.98441,-0.789284,-0.50338)" + id="linearGradient2313" + xlink:href="#linearGradient2307" + inkscape:collect="always" /> + <linearGradient + gradientUnits="userSpaceOnUse" + y2="33.339787" + x2="34.784473" + y1="7.2293582" + x1="8.6116238" + gradientTransform="matrix(1.129863,0,0,0.885063,-1.625,-1.304372)" + id="linearGradient2251" + xlink:href="#linearGradient2245" + inkscape:collect="always" /> + <linearGradient + id="linearGradient2245"> + <stop + id="stop2247" + offset="0.0000000" + style="stop-color:#dde1d9;stop-opacity:1.0000000;" /> + <stop + id="stop2249" + offset="1.0000000" + style="stop-color:#cacdc6;stop-opacity:1.0000000;" /> + </linearGradient> + <linearGradient + id="linearGradient2253"> + <stop + id="stop2255" + offset="0.0000000" + style="stop-color:#8f8f8f;stop-opacity:1.0000000;" /> + <stop + id="stop2257" + offset="1.0000000" + style="stop-color:#494949;stop-opacity:1.0000000;" /> + </linearGradient> + <linearGradient + id="linearGradient2307" + inkscape:collect="always"> + <stop + id="stop2309" + offset="0" + style="stop-color:#5a7aa4;stop-opacity:1;" /> + <stop + id="stop2311" + offset="1" + style="stop-color:#5a7aa4;stop-opacity:0;" /> + </linearGradient> + <linearGradient + id="linearGradient2328" + inkscape:collect="always"> + <stop + id="stop2330" + offset="0" + style="stop-color:#ffffff;stop-opacity:1;" /> + <stop + id="stop2332" + offset="1" + style="stop-color:#ffffff;stop-opacity:0;" /> + </linearGradient> + <linearGradient + id="linearGradient2379"> + <stop + id="stop2381" + offset="0.0000000" + style="stop-color:#1a4876;stop-opacity:1.0000000;" /> + <stop + id="stop2383" + offset="1.0000000" + style="stop-color:#3f54a3;stop-opacity:0.0000000;" /> + </linearGradient> + <linearGradient + id="linearGradient2415" + inkscape:collect="always"> + <stop + id="stop2417" + offset="0" + style="stop-color:#ffffff;stop-opacity:1;" /> + <stop + id="stop2419" + offset="1" + style="stop-color:#ffffff;stop-opacity:0;" /> + </linearGradient> + <linearGradient + id="linearGradient2454" + inkscape:collect="always"> + <stop + id="stop2456" + offset="0" + style="stop-color:#000000;stop-opacity:1;" /> + <stop + id="stop2458" + offset="1" + style="stop-color:#000000;stop-opacity:0;" /> + </linearGradient> + <linearGradient + id="linearGradient2623"> + <stop + style="stop-color:#dfdfde;stop-opacity:1.0000000;" + offset="0.0000000" + id="stop2625" /> + <stop + style="stop-color:#9d9f9a;stop-opacity:1.0000000;" + offset="1.0000000" + id="stop2627" /> + </linearGradient> + <linearGradient + inkscape:collect="always" + id="linearGradient2635"> + <stop + style="stop-color:#f9fff5;stop-opacity:1;" + offset="0" + id="stop2637" /> + <stop + style="stop-color:#f9fff5;stop-opacity:0;" + offset="1" + id="stop2639" /> + </linearGradient> + <linearGradient + id="linearGradient2667"> + <stop + style="stop-color:#ffffff;stop-opacity:1.0000000;" + offset="0.0000000" + id="stop2669" /> + <stop + style="stop-color:#fcfcff;stop-opacity:0.0000000;" + offset="1.0000000" + id="stop2671" /> + </linearGradient> + <linearGradient + id="linearGradient2675"> + <stop + style="stop-color:#5b5b97;stop-opacity:1.0000000;" + offset="0.0000000" + id="stop2677" /> + <stop + style="stop-color:#1b1b43;stop-opacity:1.0000000;" + offset="1.0000000" + id="stop2679" /> + </linearGradient> + <linearGradient + inkscape:collect="always" + id="linearGradient2683"> + <stop + style="stop-color:#000000;stop-opacity:1;" + offset="0" + id="stop2685" /> + <stop + style="stop-color:#000000;stop-opacity:0;" + offset="1" + id="stop2687" /> + </linearGradient> + <linearGradient + id="linearGradient2691"> + <stop + style="stop-color:#868686;stop-opacity:1.0000000;" + offset="0.0000000" + id="stop2693" /> + <stop + style="stop-color:#e9e9e9;stop-opacity:1.0000000;" + offset="1.0000000" + id="stop2695" /> + </linearGradient> + <linearGradient + id="linearGradient2701"> + <stop + style="stop-color:#585956;stop-opacity:1.0000000;" + offset="0.0000000" + id="stop2703" /> + <stop + style="stop-color:#bbbeb8;stop-opacity:1.0000000;" + offset="1.0000000" + id="stop2705" /> + </linearGradient> + <linearGradient + id="linearGradient2711"> + <stop + style="stop-color:#909090;stop-opacity:1.0000000;" + offset="0.0000000" + id="stop2713" /> + <stop + style="stop-color:#bebebe;stop-opacity:0.0000000;" + offset="1.0000000" + id="stop2715" /> + </linearGradient> + <linearGradient + id="linearGradient2752"> + <stop + style="stop-color:#9d9d9d;stop-opacity:1;" + offset="0" + id="stop2754" /> + <stop + style="stop-color:#b9b9b9;stop-opacity:1.0000000;" + offset="1.0000000" + id="stop2756" /> + </linearGradient> + <linearGradient + inkscape:collect="always" + id="linearGradient2985"> + <stop + style="stop-color:#d8dfd6;stop-opacity:1;" + offset="0" + id="stop2987" /> + <stop + style="stop-color:#d8dfd6;stop-opacity:0;" + offset="1" + id="stop2989" /> + </linearGradient> + <radialGradient + r="8.7662792" + fy="67.501709" + fx="12.57571" + cy="67.501709" + cx="12.57571" + gradientTransform="scale(1.925808,0.519262)" + gradientUnits="userSpaceOnUse" + id="radialGradient2003-1" + xlink:href="#linearGradient2454-1" + inkscape:collect="always" /> + <linearGradient + id="linearGradient2454-1" + inkscape:collect="always"> + <stop + id="stop2456-9" + offset="0" + style="stop-color:#000000;stop-opacity:1;" /> + <stop + id="stop2458-1" + offset="1" + style="stop-color:#000000;stop-opacity:0;" /> + </linearGradient> + <linearGradient + y2="44.878883" + x2="-23.8857" + y1="49.953003" + x1="-23.8857" + gradientTransform="scale(1.492875,0.669848)" + gradientUnits="userSpaceOnUse" + id="linearGradient2005-3" + xlink:href="#linearGradient2985-8" + inkscape:collect="always" /> + <linearGradient + inkscape:collect="always" + id="linearGradient2985-8"> + <stop + style="stop-color:#d8dfd6;stop-opacity:1;" + offset="0" + id="stop2987-7" /> + <stop + style="stop-color:#d8dfd6;stop-opacity:0;" + offset="1" + id="stop2989-4" /> + </linearGradient> + <radialGradient + r="8.7662792" + fy="67.501709" + fx="12.57571" + cy="67.501709" + cx="12.57571" + gradientTransform="scale(1.925808,0.519262)" + gradientUnits="userSpaceOnUse" + id="radialGradient2007-9" + xlink:href="#linearGradient2454-1" + inkscape:collect="always" /> + <linearGradient + y2="64.892525" + x2="12.127711" + y1="53.535141" + x1="12.206709" + gradientTransform="scale(1.816345,0.550556)" + gradientUnits="userSpaceOnUse" + id="linearGradient2009-3" + xlink:href="#linearGradient2701-1" + inkscape:collect="always" /> + <linearGradient + id="linearGradient2701-1"> + <stop + style="stop-color:#585956;stop-opacity:1.0000000;" + offset="0.0000000" + id="stop2703-3" /> + <stop + style="stop-color:#bbbeb8;stop-opacity:1.0000000;" + offset="1.0000000" + id="stop2705-8" /> + </linearGradient> + <linearGradient + y2="33.339787" + x2="34.784473" + y1="7.2293582" + x1="8.6116238" + gradientTransform="matrix(1.129863,0,0,0.885063,-1.625,-1.304372)" + gradientUnits="userSpaceOnUse" + id="linearGradient2011-7" + xlink:href="#linearGradient2245-9" + inkscape:collect="always" /> + <linearGradient + id="linearGradient2245-9"> + <stop + id="stop2247-3" + offset="0.0000000" + style="stop-color:#dde1d9;stop-opacity:1.0000000;" /> + <stop + id="stop2249-8" + offset="1.0000000" + style="stop-color:#cacdc6;stop-opacity:1.0000000;" /> + </linearGradient> + <linearGradient + y2="31.246054" + x2="32.536823" + y1="5.3817744" + x1="10.390738" + gradientTransform="scale(1.104397,0.905471)" + gradientUnits="userSpaceOnUse" + id="linearGradient2013-8" + xlink:href="#linearGradient2253-4" + inkscape:collect="always" /> + <linearGradient + id="linearGradient2253-4"> + <stop + id="stop2255-0" + offset="0.0000000" + style="stop-color:#8f8f8f;stop-opacity:1.0000000;" /> + <stop + id="stop2257-0" + offset="1.0000000" + style="stop-color:#494949;stop-opacity:1.0000000;" /> + </linearGradient> + <linearGradient + y2="8.8666229" + x2="16.315819" + y1="32.622238" + x1="19.150396" + gradientTransform="matrix(1.174139,0,0,0.945431,0.721825,-1.331524)" + gradientUnits="userSpaceOnUse" + id="linearGradient2015-8" + xlink:href="#linearGradient2675-6" + inkscape:collect="always" /> + <linearGradient + id="linearGradient2675-6"> + <stop + style="stop-color:#5b5b97;stop-opacity:1.0000000;" + offset="0.0000000" + id="stop2677-8" /> + <stop + style="stop-color:#1b1b43;stop-opacity:1.0000000;" + offset="1.0000000" + id="stop2679-2" /> + </linearGradient> + <linearGradient + y2="162.45061" + x2="3.7069974" + y1="171.29134" + x1="3.7069976" + gradientTransform="matrix(5.705159,0,0,0.17528,1,-0.679373)" + gradientUnits="userSpaceOnUse" + id="linearGradient2017-3" + xlink:href="#linearGradient2683-8" + inkscape:collect="always" /> + <linearGradient + inkscape:collect="always" + id="linearGradient2683-8"> + <stop + style="stop-color:#000000;stop-opacity:1;" + offset="0" + id="stop2685-5" /> + <stop + style="stop-color:#000000;stop-opacity:0;" + offset="1" + id="stop2687-0" /> + </linearGradient> + <linearGradient + y2="55.200756" + x2="34.974548" + y1="13.004725" + x1="17.698339" + gradientTransform="matrix(1.108069,0,0,0.902471,1,1)" + gradientUnits="userSpaceOnUse" + id="linearGradient2019-5" + xlink:href="#linearGradient2415-9" + inkscape:collect="always" /> + <linearGradient + id="linearGradient2415-9" + inkscape:collect="always"> + <stop + id="stop2417-2" + offset="0" + style="stop-color:#ffffff;stop-opacity:1;" /> + <stop + id="stop2419-6" + offset="1" + style="stop-color:#ffffff;stop-opacity:0;" /> + </linearGradient> + <linearGradient + y2="26.729263" + x2="17.199417" + y1="1.6537577" + x1="11.492236" + gradientTransform="matrix(1.238977,0,0,0.895955,0.590553,-1.331524)" + gradientUnits="userSpaceOnUse" + id="linearGradient2021-8" + xlink:href="#linearGradient2667-5" + inkscape:collect="always" /> + <linearGradient + id="linearGradient2667-5"> + <stop + style="stop-color:#ffffff;stop-opacity:1.0000000;" + offset="0.0000000" + id="stop2669-2" /> + <stop + style="stop-color:#fcfcff;stop-opacity:0.0000000;" + offset="1.0000000" + id="stop2671-8" /> + </linearGradient> + <radialGradient + r="8.7662792" + fy="67.501709" + fx="12.57571" + cy="67.501709" + cx="12.57571" + gradientTransform="scale(1.925808,0.519262)" + gradientUnits="userSpaceOnUse" + id="radialGradient2023-3" + xlink:href="#linearGradient2454-1" + inkscape:collect="always" /> + <linearGradient + y2="52.536461" + x2="18.176752" + y1="48.643234" + x1="18.316999" + gradientTransform="scale(1.129863,0.885063)" + gradientUnits="userSpaceOnUse" + id="linearGradient2025-6" + xlink:href="#linearGradient2245-9" + inkscape:collect="always" /> + <linearGradient + id="linearGradient7446"> + <stop + id="stop7448" + offset="0.0000000" + style="stop-color:#dde1d9;stop-opacity:1.0000000;" /> + <stop + id="stop7450" + offset="1.0000000" + style="stop-color:#cacdc6;stop-opacity:1.0000000;" /> + </linearGradient> + <linearGradient + y2="31.246054" + x2="32.536823" + y1="5.3817744" + x1="10.390738" + gradientTransform="scale(1.104397,0.905471)" + gradientUnits="userSpaceOnUse" + id="linearGradient2027-7" + xlink:href="#linearGradient2253-4" + inkscape:collect="always" /> + <linearGradient + id="linearGradient7453"> + <stop + id="stop7455" + offset="0.0000000" + style="stop-color:#8f8f8f;stop-opacity:1.0000000;" /> + <stop + id="stop7457" + offset="1.0000000" + style="stop-color:#494949;stop-opacity:1.0000000;" /> + </linearGradient> + <linearGradient + y2="100.20015" + x2="8.1134233" + y1="88.509071" + x1="8.1134243" + gradientTransform="scale(2.309851,0.432928)" + gradientUnits="userSpaceOnUse" + id="linearGradient2029-8" + xlink:href="#linearGradient2752-7" + inkscape:collect="always" /> + <linearGradient + id="linearGradient2752-7"> + <stop + style="stop-color:#9d9d9d;stop-opacity:1;" + offset="0" + id="stop2754-2" /> + <stop + style="stop-color:#b9b9b9;stop-opacity:1.0000000;" + offset="1.0000000" + id="stop2756-6" /> + </linearGradient> + <linearGradient + y2="100.20015" + x2="8.1134233" + y1="88.509071" + x1="8.1134243" + gradientTransform="scale(2.309851,0.432928)" + gradientUnits="userSpaceOnUse" + id="linearGradient2031-6" + xlink:href="#linearGradient2752-7" + inkscape:collect="always" /> + <linearGradient + id="linearGradient7464"> + <stop + style="stop-color:#9d9d9d;stop-opacity:1;" + offset="0" + id="stop7466" /> + <stop + style="stop-color:#b9b9b9;stop-opacity:1.0000000;" + offset="1.0000000" + id="stop7468" /> + </linearGradient> + <linearGradient + y2="100.20015" + x2="8.1134233" + y1="88.509071" + x1="8.1134243" + gradientTransform="scale(2.309851,0.432928)" + gradientUnits="userSpaceOnUse" + id="linearGradient2033-2" + xlink:href="#linearGradient2752-7" + inkscape:collect="always" /> + <linearGradient + id="linearGradient7471"> + <stop + style="stop-color:#9d9d9d;stop-opacity:1;" + offset="0" + id="stop7473" /> + <stop + style="stop-color:#b9b9b9;stop-opacity:1.0000000;" + offset="1.0000000" + id="stop7475" /> + </linearGradient> + <linearGradient + y2="74.098007" + x2="8.6485014" + y1="101.2846" + x1="13.62871" + gradientTransform="matrix(2.143634,0,0,0.466498,1,-0.508826)" + gradientUnits="userSpaceOnUse" + id="linearGradient2035-9" + xlink:href="#linearGradient2635-7" + inkscape:collect="always" /> + <linearGradient + inkscape:collect="always" + id="linearGradient2635-7"> + <stop + style="stop-color:#f9fff5;stop-opacity:1;" + offset="0" + id="stop2637-0" /> + <stop + style="stop-color:#f9fff5;stop-opacity:0;" + offset="1" + id="stop2639-3" /> + </linearGradient> + <linearGradient + y2="3.8451097" + x2="35.520542" + y1="3.9384086" + x1="34.300991" + gradientUnits="userSpaceOnUse" + id="linearGradient2037-7" + xlink:href="#linearGradient2711-2" + inkscape:collect="always" /> + <linearGradient + id="linearGradient2711-2"> + <stop + style="stop-color:#909090;stop-opacity:1.0000000;" + offset="0.0000000" + id="stop2713-3" /> + <stop + style="stop-color:#bebebe;stop-opacity:0.0000000;" + offset="1.0000000" + id="stop2715-5" /> + </linearGradient> + <linearGradient + y2="3.8451097" + x2="35.520542" + y1="3.9384086" + x1="34.300991" + gradientUnits="userSpaceOnUse" + id="linearGradient2039-1" + xlink:href="#linearGradient2711-2" + inkscape:collect="always" /> + <linearGradient + id="linearGradient7486"> + <stop + style="stop-color:#909090;stop-opacity:1.0000000;" + offset="0.0000000" + id="stop7488" /> + <stop + style="stop-color:#bebebe;stop-opacity:0.0000000;" + offset="1.0000000" + id="stop7490" /> + </linearGradient> + <linearGradient + y2="3.8451097" + x2="35.520542" + y1="3.9384086" + x1="34.300991" + gradientUnits="userSpaceOnUse" + id="linearGradient2041-7" + xlink:href="#linearGradient2711-2" + inkscape:collect="always" /> + <linearGradient + id="linearGradient7493"> + <stop + style="stop-color:#909090;stop-opacity:1.0000000;" + offset="0.0000000" + id="stop7495" /> + <stop + style="stop-color:#bebebe;stop-opacity:0.0000000;" + offset="1.0000000" + id="stop7497" /> + </linearGradient> + <linearGradient + y2="3.8451097" + x2="35.520542" + y1="3.9384086" + x1="34.300991" + gradientUnits="userSpaceOnUse" + id="linearGradient2043-8" + xlink:href="#linearGradient2711-2" + inkscape:collect="always" /> + <linearGradient + id="linearGradient7500"> + <stop + style="stop-color:#909090;stop-opacity:1.0000000;" + offset="0.0000000" + id="stop7502" /> + <stop + style="stop-color:#bebebe;stop-opacity:0.0000000;" + offset="1.0000000" + id="stop7504" /> + </linearGradient> + <linearGradient + y2="3.8451097" + x2="35.520542" + y1="3.9384086" + x1="34.300991" + gradientUnits="userSpaceOnUse" + id="linearGradient2045-9" + xlink:href="#linearGradient2711-2" + inkscape:collect="always" /> + <linearGradient + id="linearGradient7507"> + <stop + style="stop-color:#909090;stop-opacity:1.0000000;" + offset="0.0000000" + id="stop7509" /> + <stop + style="stop-color:#bebebe;stop-opacity:0.0000000;" + offset="1.0000000" + id="stop7511" /> + </linearGradient> + <radialGradient + r="8.7662792" + fy="67.501709" + fx="12.57571" + cy="67.501709" + cx="12.57571" + gradientTransform="scale(1.925808,0.519262)" + gradientUnits="userSpaceOnUse" + id="radialGradient2003-1-5" + xlink:href="#linearGradient2454-1-6" + inkscape:collect="always" /> + <linearGradient + id="linearGradient2454-1-6" + inkscape:collect="always"> + <stop + id="stop2456-9-0" + offset="0" + style="stop-color:#000000;stop-opacity:1;" /> + <stop + id="stop2458-1-6" + offset="1" + style="stop-color:#000000;stop-opacity:0;" /> + </linearGradient> + <linearGradient + y2="44.878883" + x2="-23.8857" + y1="49.953003" + x1="-23.8857" + gradientTransform="scale(1.492875,0.669848)" + gradientUnits="userSpaceOnUse" + id="linearGradient2005-3-2" + xlink:href="#linearGradient2985-8-6" + inkscape:collect="always" /> + <linearGradient + inkscape:collect="always" + id="linearGradient2985-8-6"> + <stop + style="stop-color:#d8dfd6;stop-opacity:1;" + offset="0" + id="stop2987-7-9" /> + <stop + style="stop-color:#d8dfd6;stop-opacity:0;" + offset="1" + id="stop2989-4-9" /> + </linearGradient> + <radialGradient + r="8.7662792" + fy="67.501709" + fx="12.57571" + cy="67.501709" + cx="12.57571" + gradientTransform="scale(1.925808,0.519262)" + gradientUnits="userSpaceOnUse" + id="radialGradient2007-9-2" + xlink:href="#linearGradient2454-1-6" + inkscape:collect="always" /> + <linearGradient + y2="64.892525" + x2="12.127711" + y1="53.535141" + x1="12.206709" + gradientTransform="scale(1.816345,0.550556)" + gradientUnits="userSpaceOnUse" + id="linearGradient2009-3-9" + xlink:href="#linearGradient2701-1-6" + inkscape:collect="always" /> + <linearGradient + id="linearGradient2701-1-6"> + <stop + style="stop-color:#585956;stop-opacity:1.0000000;" + offset="0.0000000" + id="stop2703-3-5" /> + <stop + style="stop-color:#bbbeb8;stop-opacity:1.0000000;" + offset="1.0000000" + id="stop2705-8-5" /> + </linearGradient> + <linearGradient + y2="33.339787" + x2="34.784473" + y1="7.2293582" + x1="8.6116238" + gradientTransform="matrix(1.129863,0,0,0.885063,-1.625,-1.304372)" + gradientUnits="userSpaceOnUse" + id="linearGradient2011-7-3" + xlink:href="#linearGradient2245-9-8" + inkscape:collect="always" /> + <linearGradient + id="linearGradient2245-9-8"> + <stop + id="stop2247-3-6" + offset="0.0000000" + style="stop-color:#dde1d9;stop-opacity:1.0000000;" /> + <stop + id="stop2249-8-7" + offset="1.0000000" + style="stop-color:#cacdc6;stop-opacity:1.0000000;" /> + </linearGradient> + <linearGradient + y2="31.246054" + x2="32.536823" + y1="5.3817744" + x1="10.390738" + gradientTransform="scale(1.104397,0.905471)" + gradientUnits="userSpaceOnUse" + id="linearGradient2013-8-3" + xlink:href="#linearGradient2253-4-6" + inkscape:collect="always" /> + <linearGradient + id="linearGradient2253-4-6"> + <stop + id="stop2255-0-0" + offset="0.0000000" + style="stop-color:#8f8f8f;stop-opacity:1.0000000;" /> + <stop + id="stop2257-0-2" + offset="1.0000000" + style="stop-color:#494949;stop-opacity:1.0000000;" /> + </linearGradient> + <linearGradient + y2="8.8666229" + x2="16.315819" + y1="32.622238" + x1="19.150396" + gradientTransform="matrix(1.174139,0,0,0.945431,0.721825,-1.331524)" + gradientUnits="userSpaceOnUse" + id="linearGradient2015-8-6" + xlink:href="#linearGradient2675-6-9" + inkscape:collect="always" /> + <linearGradient + id="linearGradient2675-6-9"> + <stop + style="stop-color:#5b5b97;stop-opacity:1.0000000;" + offset="0.0000000" + id="stop2677-8-3" /> + <stop + style="stop-color:#1b1b43;stop-opacity:1.0000000;" + offset="1.0000000" + id="stop2679-2-0" /> + </linearGradient> + <linearGradient + y2="162.45061" + x2="3.7069974" + y1="171.29134" + x1="3.7069976" + gradientTransform="matrix(5.705159,0,0,0.17528,1,-0.679373)" + gradientUnits="userSpaceOnUse" + id="linearGradient2017-3-8" + xlink:href="#linearGradient2683-8-7" + inkscape:collect="always" /> + <linearGradient + inkscape:collect="always" + id="linearGradient2683-8-7"> + <stop + style="stop-color:#000000;stop-opacity:1;" + offset="0" + id="stop2685-5-6" /> + <stop + style="stop-color:#000000;stop-opacity:0;" + offset="1" + id="stop2687-0-5" /> + </linearGradient> + <linearGradient + y2="55.200756" + x2="34.974548" + y1="13.004725" + x1="17.698339" + gradientTransform="matrix(1.108069,0,0,0.902471,1,1)" + gradientUnits="userSpaceOnUse" + id="linearGradient2019-5-2" + xlink:href="#linearGradient2415-9-4" + inkscape:collect="always" /> + <linearGradient + id="linearGradient2415-9-4" + inkscape:collect="always"> + <stop + id="stop2417-2-0" + offset="0" + style="stop-color:#ffffff;stop-opacity:1;" /> + <stop + id="stop2419-6-0" + offset="1" + style="stop-color:#ffffff;stop-opacity:0;" /> + </linearGradient> + <linearGradient + y2="26.729263" + x2="17.199417" + y1="1.6537577" + x1="11.492236" + gradientTransform="matrix(1.238977,0,0,0.895955,0.590553,-1.331524)" + gradientUnits="userSpaceOnUse" + id="linearGradient2021-8-6" + xlink:href="#linearGradient2667-5-8" + inkscape:collect="always" /> + <linearGradient + id="linearGradient2667-5-8"> + <stop + style="stop-color:#ffffff;stop-opacity:1.0000000;" + offset="0.0000000" + id="stop2669-2-5" /> + <stop + style="stop-color:#fcfcff;stop-opacity:0.0000000;" + offset="1.0000000" + id="stop2671-8-4" /> + </linearGradient> + <radialGradient + r="8.7662792" + fy="67.501709" + fx="12.57571" + cy="67.501709" + cx="12.57571" + gradientTransform="scale(1.925808,0.519262)" + gradientUnits="userSpaceOnUse" + id="radialGradient2023-3-9" + xlink:href="#linearGradient2454-1-6" + inkscape:collect="always" /> + <linearGradient + y2="52.536461" + x2="18.176752" + y1="48.643234" + x1="18.316999" + gradientTransform="scale(1.129863,0.885063)" + gradientUnits="userSpaceOnUse" + id="linearGradient2025-6-4" + xlink:href="#linearGradient2245-9-8" + inkscape:collect="always" /> + <linearGradient + id="linearGradient7842"> + <stop + id="stop7844" + offset="0.0000000" + style="stop-color:#dde1d9;stop-opacity:1.0000000;" /> + <stop + id="stop7846" + offset="1.0000000" + style="stop-color:#cacdc6;stop-opacity:1.0000000;" /> + </linearGradient> + <linearGradient + y2="31.246054" + x2="32.536823" + y1="5.3817744" + x1="10.390738" + gradientTransform="scale(1.104397,0.905471)" + gradientUnits="userSpaceOnUse" + id="linearGradient2027-7-6" + xlink:href="#linearGradient2253-4-6" + inkscape:collect="always" /> + <linearGradient + id="linearGradient7849"> + <stop + id="stop7851" + offset="0.0000000" + style="stop-color:#8f8f8f;stop-opacity:1.0000000;" /> + <stop + id="stop7853" + offset="1.0000000" + style="stop-color:#494949;stop-opacity:1.0000000;" /> + </linearGradient> + <linearGradient + y2="100.20015" + x2="8.1134233" + y1="88.509071" + x1="8.1134243" + gradientTransform="scale(2.309851,0.432928)" + gradientUnits="userSpaceOnUse" + id="linearGradient2029-8-8" + xlink:href="#linearGradient2752-7-3" + inkscape:collect="always" /> + <linearGradient + id="linearGradient2752-7-3"> + <stop + style="stop-color:#9d9d9d;stop-opacity:1;" + offset="0" + id="stop2754-2-2" /> + <stop + style="stop-color:#b9b9b9;stop-opacity:1.0000000;" + offset="1.0000000" + id="stop2756-6-3" /> + </linearGradient> + <linearGradient + y2="100.20015" + x2="8.1134233" + y1="88.509071" + x1="8.1134243" + gradientTransform="scale(2.309851,0.432928)" + gradientUnits="userSpaceOnUse" + id="linearGradient2031-6-6" + xlink:href="#linearGradient2752-7-3" + inkscape:collect="always" /> + <linearGradient + id="linearGradient7860"> + <stop + style="stop-color:#9d9d9d;stop-opacity:1;" + offset="0" + id="stop7862" /> + <stop + style="stop-color:#b9b9b9;stop-opacity:1.0000000;" + offset="1.0000000" + id="stop7864" /> + </linearGradient> + <linearGradient + y2="100.20015" + x2="8.1134233" + y1="88.509071" + x1="8.1134243" + gradientTransform="scale(2.309851,0.432928)" + gradientUnits="userSpaceOnUse" + id="linearGradient2033-2-2" + xlink:href="#linearGradient2752-7-3" + inkscape:collect="always" /> + <linearGradient + id="linearGradient7867"> + <stop + style="stop-color:#9d9d9d;stop-opacity:1;" + offset="0" + id="stop7869" /> + <stop + style="stop-color:#b9b9b9;stop-opacity:1.0000000;" + offset="1.0000000" + id="stop7871" /> + </linearGradient> + <linearGradient + y2="74.098007" + x2="8.6485014" + y1="101.2846" + x1="13.62871" + gradientTransform="matrix(2.143634,0,0,0.466498,1,-0.508826)" + gradientUnits="userSpaceOnUse" + id="linearGradient2035-9-2" + xlink:href="#linearGradient2635-7-4" + inkscape:collect="always" /> + <linearGradient + inkscape:collect="always" + id="linearGradient2635-7-4"> + <stop + style="stop-color:#f9fff5;stop-opacity:1;" + offset="0" + id="stop2637-0-7" /> + <stop + style="stop-color:#f9fff5;stop-opacity:0;" + offset="1" + id="stop2639-3-0" /> + </linearGradient> + <linearGradient + y2="3.8451097" + x2="35.520542" + y1="3.9384086" + x1="34.300991" + gradientUnits="userSpaceOnUse" + id="linearGradient2037-7-4" + xlink:href="#linearGradient2711-2-9" + inkscape:collect="always" /> + <linearGradient + id="linearGradient2711-2-9"> + <stop + style="stop-color:#909090;stop-opacity:1.0000000;" + offset="0.0000000" + id="stop2713-3-6" /> + <stop + style="stop-color:#bebebe;stop-opacity:0.0000000;" + offset="1.0000000" + id="stop2715-5-5" /> + </linearGradient> + <linearGradient + y2="3.8451097" + x2="35.520542" + y1="3.9384086" + x1="34.300991" + gradientUnits="userSpaceOnUse" + id="linearGradient2039-1-4" + xlink:href="#linearGradient2711-2-9" + inkscape:collect="always" /> + <linearGradient + id="linearGradient7882"> + <stop + style="stop-color:#909090;stop-opacity:1.0000000;" + offset="0.0000000" + id="stop7884" /> + <stop + style="stop-color:#bebebe;stop-opacity:0.0000000;" + offset="1.0000000" + id="stop7886" /> + </linearGradient> + <linearGradient + y2="3.8451097" + x2="35.520542" + y1="3.9384086" + x1="34.300991" + gradientUnits="userSpaceOnUse" + id="linearGradient2041-7-6" + xlink:href="#linearGradient2711-2-9" + inkscape:collect="always" /> + <linearGradient + id="linearGradient7889"> + <stop + style="stop-color:#909090;stop-opacity:1.0000000;" + offset="0.0000000" + id="stop7891" /> + <stop + style="stop-color:#bebebe;stop-opacity:0.0000000;" + offset="1.0000000" + id="stop7893" /> + </linearGradient> + <linearGradient + y2="3.8451097" + x2="35.520542" + y1="3.9384086" + x1="34.300991" + gradientUnits="userSpaceOnUse" + id="linearGradient2043-8-4" + xlink:href="#linearGradient2711-2-9" + inkscape:collect="always" /> + <linearGradient + id="linearGradient7896"> + <stop + style="stop-color:#909090;stop-opacity:1.0000000;" + offset="0.0000000" + id="stop7898" /> + <stop + style="stop-color:#bebebe;stop-opacity:0.0000000;" + offset="1.0000000" + id="stop7900" /> + </linearGradient> + <linearGradient + y2="3.8451097" + x2="35.520542" + y1="3.9384086" + x1="34.300991" + gradientUnits="userSpaceOnUse" + id="linearGradient2045-9-2" + xlink:href="#linearGradient2711-2-9" + inkscape:collect="always" /> + <linearGradient + id="linearGradient7903"> + <stop + style="stop-color:#909090;stop-opacity:1.0000000;" + offset="0.0000000" + id="stop7905" /> + <stop + style="stop-color:#bebebe;stop-opacity:0.0000000;" + offset="1.0000000" + id="stop7907" /> + </linearGradient> + </defs> + <sodipodi:namedview + id="base" + pagecolor="#ffffff" + bordercolor="#666666" + borderopacity="1.0" + inkscape:pageopacity="0.0" + inkscape:pageshadow="2" + inkscape:zoom="11.2" + inkscape:cx="1004.3144" + inkscape:cy="275.05557" + inkscape:document-units="px" + inkscape:current-layer="layer1" + showgrid="false" /> + <metadata + id="metadata7"> + <rdf:RDF> + <cc:Work + rdf:about=""> + <dc:format>image/svg+xml</dc:format> + <dc:type + rdf:resource="http://purl.org/dc/dcmitype/StillImage" /> + <dc:title /> + </cc:Work> + </rdf:RDF> + </metadata> + <g + inkscape:label="Layer 1" + inkscape:groupmode="layer" + id="layer1" + transform="translate(0,-308.2677)"> + <path + sodipodi:type="arc" + style="opacity:0.25099996;color:#000000;fill:url(#radialGradient3909);fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:0;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;marker:none;visibility:visible;display:inline;overflow:visible;enable-background:accumulate" + id="path3109-5" + sodipodi:cx="144.28572" + sodipodi:cy="673.07648" + sodipodi:rx="115.71429" + sodipodi:ry="105" + d="m 260.00001,673.07648 c 0,57.9899 -51.80705,105 -115.71429,105 -63.907235,0 -115.714286,-47.0101 -115.714286,-105 0,-57.9899 51.807051,-105 115.714286,-105 63.90724,0 115.71429,47.0101 115.71429,105 z" + transform="matrix(1,0,0,1.1360544,60.857137,-306.28931)" /> + <image + y="370.14789" + x="132.64285" + id="image3063-0" + xlink:href="file:///source/git/clean-pcp-gui/man/html/images/rack.jpg" + height="175.28572" + width="147.28572" /> + <path + sodipodi:type="arc" + style="opacity:0.25099996;color:#000000;fill:url(#radialGradient5519);fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:0;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;marker:none;visibility:visible;display:inline;overflow:visible;enable-background:accumulate" + id="path3109-5-5" + sodipodi:cx="144.28572" + sodipodi:cy="673.07648" + sodipodi:rx="115.71429" + sodipodi:ry="105" + d="m 260.00001,673.07648 c 0,57.9899 -51.80705,105 -115.71429,105 -63.907235,0 -115.714286,-47.0101 -115.714286,-105 0,-57.9899 51.807051,-105 115.714286,-105 63.90724,0 115.71429,47.0101 115.71429,105 z" + transform="matrix(1,0,0,1.1360544,63.14284,115.9964)" /> + <image + y="793.39722" + x="133.30974" + id="image3063" + xlink:href="file:///source/git/clean-pcp-gui/man/html/images/rack.jpg" + height="175.28572" + width="147.28572" /> + <path + sodipodi:type="arc" + style="opacity:0.25099996;color:#000000;fill:url(#radialGradient3885);fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:0;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;marker:none;visibility:visible;display:inline;overflow:visible;enable-background:accumulate" + id="path3109" + sodipodi:cx="144.28572" + sodipodi:cy="673.07648" + sodipodi:rx="115.71429" + sodipodi:ry="105" + d="m 260.00001,673.07648 c 0,57.9899 -51.80705,105 -115.71429,105 -63.907235,0 -115.714286,-47.0101 -115.714286,-105 0,-57.9899 51.807051,-105 115.714286,-105 63.90724,0 115.71429,47.0101 115.71429,105 z" + transform="matrix(1,0,0,1.1360544,-23.428574,-86.7179)" /> + <image + y="584.7193" + x="47.214283" + id="image3063-1-6" + xlink:href="file:///source/git/clean-pcp-gui/man/html/images/rack.jpg" + height="175.28572" + width="147.28572" /> + <path + sodipodi:type="arc" + style="opacity:0.24892704;color:#000000;fill:url(#radialGradient6332);fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:0;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;marker:none;visibility:visible;display:inline;overflow:visible;enable-background:accumulate" + id="path3109-7" + sodipodi:cx="144.28572" + sodipodi:cy="673.07648" + sodipodi:rx="115.71429" + sodipodi:ry="105" + d="m 260.00001,673.07648 c 0,57.9899 -51.80705,105 -115.71429,105 -63.907235,0 -115.714286,-47.0101 -115.714286,-105 0,-57.9899 51.807051,-105 115.714286,-105 63.90724,0 115.71429,47.0101 115.71429,105 z" + transform="matrix(1,0,0,1.2244898,771.48948,-174.88997)" /> + <image + y="561.21387" + x="841.13232" + id="image4099" + xlink:href="file:///source/git/clean-pcp-gui/man/html/images/server.jpg" + height="29" + width="150.14285" /> + <g + id="g4500" + transform="matrix(10.71203,0,0,11.079441,828.98022,578.12464)"> + <g + inkscape:label="Shadow" + id="layer6" /> + <g + id="layer1-7" + inkscape:label="Base" + style="display:inline" /> + <g + style="display:inline" + inkscape:label="Text" + id="layer5"> + <g + transform="matrix(0.388981,0,0,0.327274,-1.220361,0.172154)" + id="g3161"> + <path + sodipodi:type="arc" + style="opacity:0.7836257;color:#000000;fill:url(#radialGradient3195);fill-opacity:1;fill-rule:evenodd;stroke:none;stroke-width:2;marker:none;visibility:visible;display:inline;overflow:visible" + id="path3667" + sodipodi:cx="24.306795" + sodipodi:cy="42.07798" + sodipodi:rx="15.821514" + sodipodi:ry="4.5078058" + d="m 40.128309,42.07798 c 0,2.489592 -7.083533,4.507806 -15.821514,4.507806 -8.737981,0 -15.821514,-2.018214 -15.821514,-4.507806 0,-2.489592 7.083533,-4.507806 15.821514,-4.507806 8.737981,0 15.821514,2.018214 15.821514,4.507806 z" + transform="translate(0,0.707108)" /> + <rect + style="color:#000000;fill:url(#radialGradient3197);fill-opacity:1;fill-rule:nonzero;stroke:url(#radialGradient3199);stroke-width:1;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-opacity:1;stroke-dashoffset:0;marker:none;visibility:visible;display:block;overflow:visible" + id="rect15391" + width="34.875" + height="40.920494" + x="6.6035528" + y="3.6464462" + ry="1.1490486" /> + <rect + style="color:#000000;fill:none;stroke:url(#radialGradient3201);stroke-width:1;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-opacity:1;stroke-dashoffset:0;marker:none;visibility:visible;display:block;overflow:visible" + id="rect15660" + width="32.775887" + height="38.946384" + x="7.6660538" + y="4.5839462" + ry="0.14904857" + rx="0.14904857" /> + <g + style="display:inline" + transform="translate(0.646447,-0.03798933)" + id="g2270"> + <g + id="g1440" + style="fill:#ffffff;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-miterlimit:4" + transform="matrix(0.229703,0,0,0.229703,4.967081,4.244972)"> + <radialGradient + id="radialGradient1442" + cx="20.892099" + cy="114.5684" + r="5.256" + fx="20.892099" + fy="114.5684" + gradientUnits="userSpaceOnUse"> + <stop + offset="0" + style="stop-color:#F0F0F0" + id="stop1444" /> + <stop + offset="1" + style="stop-color:#474747" + id="stop1446" /> + </radialGradient> + <path + style="stroke:none" + d="m 23.428,113.07 c 0,1.973 -1.6,3.572 -3.573,3.572 -1.974,0 -3.573,-1.6 -3.573,-3.572 0,-1.974 1.6,-3.573 3.573,-3.573 1.973,0 3.573,1.6 3.573,3.573 z" + id="path1448" + inkscape:connector-curvature="0" /> + <radialGradient + id="radialGradient1450" + cx="20.892099" + cy="64.567902" + r="5.257" + fx="20.892099" + fy="64.567902" + gradientUnits="userSpaceOnUse"> + <stop + offset="0" + style="stop-color:#F0F0F0" + id="stop1452" /> + <stop + offset="1" + style="stop-color:#474747" + id="stop1454" /> + </radialGradient> + <path + style="stroke:none" + d="m 23.428,63.07 c 0,1.973 -1.6,3.573 -3.573,3.573 -1.974,0 -3.573,-1.6 -3.573,-3.573 0,-1.974 1.6,-3.573 3.573,-3.573 1.973,0 3.573,1.6 3.573,3.573 z" + id="path1456" + inkscape:connector-curvature="0" /> + </g> + <path + style="fill:url(#radialGradient3203);fill-rule:nonzero;stroke:none" + d="m 9.9950109,29.952326 c 0,0.453204 -0.3675248,0.820499 -0.8207288,0.820499 -0.4534338,0 -0.8207289,-0.367524 -0.8207289,-0.820499 0,-0.453434 0.3675248,-0.820729 0.8207289,-0.820729 0.453204,0 0.8207288,0.367525 0.8207288,0.820729 z" + id="path15570" + inkscape:connector-curvature="0" /> + <path + style="fill:url(#radialGradient3205);fill-rule:nonzero;stroke:none" + d="m 9.9950109,18.467176 c 0,0.453204 -0.3675248,0.820729 -0.8207288,0.820729 -0.4534338,0 -0.8207289,-0.367525 -0.8207289,-0.820729 0,-0.453434 0.3675248,-0.820729 0.8207289,-0.820729 0.453204,0 0.8207288,0.367525 0.8207288,0.820729 z" + id="path15577" + inkscape:connector-curvature="0" /> + </g> + <path + style="fill:none;stroke:#000000;stroke-width:0.98855311;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:0.01754384;display:inline" + d="m 11.505723,5.4942766 0,37.9065924" + id="path15672" + sodipodi:nodetypes="cc" + inkscape:connector-curvature="0" /> + <path + style="fill:none;stroke:#ffffff;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:0.20467828;display:inline" + d="m 12.5,5.0205154 0,38.0177126" + id="path15674" + sodipodi:nodetypes="cc" + inkscape:connector-curvature="0" /> + <g + transform="matrix(0.909091,0,0,1,2.363628,0)" + id="g2253"> + <rect + style="color:#000000;fill:#9b9b9b;fill-opacity:0.54970757;fill-rule:nonzero;stroke:none;stroke-width:1;marker:none;visibility:visible;display:block;overflow:visible" + id="rect15686" + width="22.000004" + height="1" + x="15.000002" + y="9" + rx="0.15156493" + ry="0.065390877" /> + <rect + style="color:#000000;fill:#9b9b9b;fill-opacity:0.54970757;fill-rule:nonzero;stroke:none;stroke-width:1;marker:none;visibility:visible;display:block;overflow:visible" + id="rect15688" + width="22.000004" + height="1" + x="15.000002" + y="11" + rx="0.15156493" + ry="0.065390877" /> + <rect + style="color:#000000;fill:#9b9b9b;fill-opacity:0.54970757;fill-rule:nonzero;stroke:none;stroke-width:1;marker:none;visibility:visible;display:block;overflow:visible" + id="rect15690" + width="22.000004" + height="1" + x="15.000002" + y="13" + rx="0.15156493" + ry="0.065390877" /> + <rect + style="color:#000000;fill:#9b9b9b;fill-opacity:0.54970757;fill-rule:nonzero;stroke:none;stroke-width:1;marker:none;visibility:visible;display:block;overflow:visible" + id="rect15692" + width="22.000004" + height="1" + x="15.000002" + y="15" + rx="0.15156493" + ry="0.065390877" /> + <rect + style="color:#000000;fill:#9b9b9b;fill-opacity:0.54970757;fill-rule:nonzero;stroke:none;stroke-width:1;marker:none;visibility:visible;display:block;overflow:visible" + id="rect15694" + width="22.000004" + height="1" + x="15.000002" + y="17" + rx="0.15156493" + ry="0.065390877" /> + <rect + style="color:#000000;fill:#9b9b9b;fill-opacity:0.54970757;fill-rule:nonzero;stroke:none;stroke-width:1;marker:none;visibility:visible;display:block;overflow:visible" + id="rect15696" + width="22.000004" + height="1" + x="15.000002" + y="19" + rx="0.15156493" + ry="0.065390877" /> + <rect + style="color:#000000;fill:#9b9b9b;fill-opacity:0.54970757;fill-rule:nonzero;stroke:none;stroke-width:1;marker:none;visibility:visible;display:block;overflow:visible" + id="rect15698" + width="22.000004" + height="1" + x="15.000002" + y="21" + rx="0.15156493" + ry="0.065390877" /> + <rect + style="color:#000000;fill:#9b9b9b;fill-opacity:0.54970757;fill-rule:nonzero;stroke:none;stroke-width:1;marker:none;visibility:visible;display:block;overflow:visible" + id="rect15700" + width="22.000004" + height="1" + x="15.000002" + y="23" + rx="0.15156493" + ry="0.065390877" /> + <rect + style="color:#000000;fill:#9b9b9b;fill-opacity:0.54970757;fill-rule:nonzero;stroke:none;stroke-width:1;marker:none;visibility:visible;display:block;overflow:visible" + id="rect15732" + width="9.9000053" + height="1" + x="14.999992" + y="25" + rx="0.068204239" + ry="0.065390877" /> + <rect + style="color:#000000;fill:#9b9b9b;fill-opacity:0.54970757;fill-rule:nonzero;stroke:none;stroke-width:1;marker:none;visibility:visible;display:block;overflow:visible" + id="rect15736" + width="22.000004" + height="1" + x="14.999992" + y="29" + rx="0.15156493" + ry="0.065390877" /> + <rect + style="color:#000000;fill:#9b9b9b;fill-opacity:0.54970757;fill-rule:nonzero;stroke:none;stroke-width:1;marker:none;visibility:visible;display:block;overflow:visible" + id="rect15738" + width="22.000004" + height="1" + x="14.999992" + y="31" + rx="0.15156493" + ry="0.065390877" /> + <rect + style="color:#000000;fill:#9b9b9b;fill-opacity:0.54970757;fill-rule:nonzero;stroke:none;stroke-width:1;marker:none;visibility:visible;display:block;overflow:visible" + id="rect15740" + width="22.000004" + height="1" + x="14.999992" + y="33" + rx="0.15156493" + ry="0.065390877" /> + <rect + style="color:#000000;fill:#9b9b9b;fill-opacity:0.54970757;fill-rule:nonzero;stroke:none;stroke-width:1;marker:none;visibility:visible;display:block;overflow:visible" + id="rect15742" + width="22.000004" + height="1" + x="14.999992" + y="35" + rx="0.15156493" + ry="0.065390877" /> + <rect + style="color:#000000;fill:#9b9b9b;fill-opacity:0.54970757;fill-rule:nonzero;stroke:none;stroke-width:1;marker:none;visibility:visible;display:block;overflow:visible" + id="rect15744" + width="15.400014" + height="1" + x="14.999992" + y="37" + rx="0.10609552" + ry="0.065390877" /> + </g> + </g> + </g> + </g> + <g + id="g4500-1" + transform="matrix(6.0278296,0,0,7.3216608,835.90486,631.73013)"> + <g + inkscape:label="Shadow" + id="layer6-7" /> + <g + id="layer1-7-2" + inkscape:label="Base" + style="display:inline" /> + <g + style="display:inline" + inkscape:label="Text" + id="layer5-7"> + <g + transform="matrix(0.388981,0,0,0.327274,-1.220361,0.172154)" + id="g3161-2"> + <path + sodipodi:type="arc" + style="opacity:0.7836257;color:#000000;fill:url(#radialGradient3195-8);fill-opacity:1;fill-rule:evenodd;stroke:none;stroke-width:2;marker:none;visibility:visible;display:inline;overflow:visible" + id="path3667-2" + sodipodi:cx="24.306795" + sodipodi:cy="42.07798" + sodipodi:rx="15.821514" + sodipodi:ry="4.5078058" + d="m 40.128309,42.07798 c 0,2.489592 -7.083533,4.507806 -15.821514,4.507806 -8.737981,0 -15.821514,-2.018214 -15.821514,-4.507806 0,-2.489592 7.083533,-4.507806 15.821514,-4.507806 8.737981,0 15.821514,2.018214 15.821514,4.507806 z" + transform="translate(0,0.707108)" /> + <rect + style="color:#000000;fill:url(#radialGradient3197-4);fill-opacity:1;fill-rule:nonzero;stroke:url(#radialGradient3199-9);stroke-width:1;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-opacity:1;stroke-dashoffset:0;marker:none;visibility:visible;display:block;overflow:visible" + id="rect15391-6" + width="34.875" + height="40.920494" + x="6.6035528" + y="3.6464462" + ry="1.1490486" /> + <rect + style="color:#000000;fill:none;stroke:url(#radialGradient3201-8);stroke-width:1;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-opacity:1;stroke-dashoffset:0;marker:none;visibility:visible;display:block;overflow:visible" + id="rect15660-1" + width="32.775887" + height="38.946384" + x="7.6660538" + y="4.5839462" + ry="0.14904857" + rx="0.14904857" /> + <g + style="display:inline" + transform="translate(0.646447,-0.03798933)" + id="g2270-0"> + <g + id="g1440-6" + style="fill:#ffffff;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-miterlimit:4" + transform="matrix(0.229703,0,0,0.229703,4.967081,4.244972)"> + <radialGradient + id="radialGradient1442-1" + cx="20.892099" + cy="114.5684" + r="5.256" + fx="20.892099" + fy="114.5684" + gradientUnits="userSpaceOnUse"> + <stop + offset="0" + style="stop-color:#F0F0F0" + id="stop1444-5" /> + <stop + offset="1" + style="stop-color:#474747" + id="stop1446-9" /> + </radialGradient> + <path + style="stroke:none" + d="m 23.428,113.07 c 0,1.973 -1.6,3.572 -3.573,3.572 -1.974,0 -3.573,-1.6 -3.573,-3.572 0,-1.974 1.6,-3.573 3.573,-3.573 1.973,0 3.573,1.6 3.573,3.573 z" + id="path1448-4" + inkscape:connector-curvature="0" /> + <radialGradient + id="radialGradient1450-9" + cx="20.892099" + cy="64.567902" + r="5.257" + fx="20.892099" + fy="64.567902" + gradientUnits="userSpaceOnUse"> + <stop + offset="0" + style="stop-color:#F0F0F0" + id="stop1452-0" /> + <stop + offset="1" + style="stop-color:#474747" + id="stop1454-9" /> + </radialGradient> + <path + style="stroke:none" + d="m 23.428,63.07 c 0,1.973 -1.6,3.573 -3.573,3.573 -1.974,0 -3.573,-1.6 -3.573,-3.573 0,-1.974 1.6,-3.573 3.573,-3.573 1.973,0 3.573,1.6 3.573,3.573 z" + id="path1456-1" + inkscape:connector-curvature="0" /> + </g> + <path + style="fill:url(#radialGradient3203-6);fill-rule:nonzero;stroke:none" + d="m 9.9950109,29.952326 c 0,0.453204 -0.3675248,0.820499 -0.8207288,0.820499 -0.4534338,0 -0.8207289,-0.367524 -0.8207289,-0.820499 0,-0.453434 0.3675248,-0.820729 0.8207289,-0.820729 0.453204,0 0.8207288,0.367525 0.8207288,0.820729 z" + id="path15570-7" + inkscape:connector-curvature="0" /> + <path + style="fill:url(#radialGradient3205-0);fill-rule:nonzero;stroke:none" + d="m 9.9950109,18.467176 c 0,0.453204 -0.3675248,0.820729 -0.8207288,0.820729 -0.4534338,0 -0.8207289,-0.367525 -0.8207289,-0.820729 0,-0.453434 0.3675248,-0.820729 0.8207289,-0.820729 0.453204,0 0.8207288,0.367525 0.8207288,0.820729 z" + id="path15577-7" + inkscape:connector-curvature="0" /> + </g> + <path + style="fill:none;stroke:#000000;stroke-width:0.98855311;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:0.01754384;display:inline" + d="m 11.505723,5.4942766 0,37.9065924" + id="path15672-1" + sodipodi:nodetypes="cc" + inkscape:connector-curvature="0" /> + <path + style="fill:none;stroke:#ffffff;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:0.20467828;display:inline" + d="m 12.5,5.0205154 0,38.0177126" + id="path15674-1" + sodipodi:nodetypes="cc" + inkscape:connector-curvature="0" /> + <g + transform="matrix(0.909091,0,0,1,2.363628,0)" + id="g2253-5"> + <rect + style="color:#000000;fill:#9b9b9b;fill-opacity:0.54970757;fill-rule:nonzero;stroke:none;stroke-width:1;marker:none;visibility:visible;display:block;overflow:visible" + id="rect15686-9" + width="22.000004" + height="1" + x="15.000002" + y="9" + rx="0.15156493" + ry="0.065390877" /> + <rect + style="color:#000000;fill:#9b9b9b;fill-opacity:0.54970757;fill-rule:nonzero;stroke:none;stroke-width:1;marker:none;visibility:visible;display:block;overflow:visible" + id="rect15688-7" + width="22.000004" + height="1" + x="15.000002" + y="11" + rx="0.15156493" + ry="0.065390877" /> + <rect + style="color:#000000;fill:#9b9b9b;fill-opacity:0.54970757;fill-rule:nonzero;stroke:none;stroke-width:1;marker:none;visibility:visible;display:block;overflow:visible" + id="rect15690-7" + width="22.000004" + height="1" + x="15.000002" + y="13" + rx="0.15156493" + ry="0.065390877" /> + <rect + style="color:#000000;fill:#9b9b9b;fill-opacity:0.54970757;fill-rule:nonzero;stroke:none;stroke-width:1;marker:none;visibility:visible;display:block;overflow:visible" + id="rect15692-6" + width="22.000004" + height="1" + x="15.000002" + y="15" + rx="0.15156493" + ry="0.065390877" /> + <rect + style="color:#000000;fill:#9b9b9b;fill-opacity:0.54970757;fill-rule:nonzero;stroke:none;stroke-width:1;marker:none;visibility:visible;display:block;overflow:visible" + id="rect15694-7" + width="22.000004" + height="1" + x="15.000002" + y="17" + rx="0.15156493" + ry="0.065390877" /> + <rect + style="color:#000000;fill:#9b9b9b;fill-opacity:0.54970757;fill-rule:nonzero;stroke:none;stroke-width:1;marker:none;visibility:visible;display:block;overflow:visible" + id="rect15696-3" + width="22.000004" + height="1" + x="15.000002" + y="19" + rx="0.15156493" + ry="0.065390877" /> + <rect + style="color:#000000;fill:#9b9b9b;fill-opacity:0.54970757;fill-rule:nonzero;stroke:none;stroke-width:1;marker:none;visibility:visible;display:block;overflow:visible" + id="rect15698-6" + width="22.000004" + height="1" + x="15.000002" + y="21" + rx="0.15156493" + ry="0.065390877" /> + <rect + style="color:#000000;fill:#9b9b9b;fill-opacity:0.54970757;fill-rule:nonzero;stroke:none;stroke-width:1;marker:none;visibility:visible;display:block;overflow:visible" + id="rect15700-5" + width="22.000004" + height="1" + x="15.000002" + y="23" + rx="0.15156493" + ry="0.065390877" /> + <rect + style="color:#000000;fill:#9b9b9b;fill-opacity:0.54970757;fill-rule:nonzero;stroke:none;stroke-width:1;marker:none;visibility:visible;display:block;overflow:visible" + id="rect15732-6" + width="9.9000053" + height="1" + x="14.999992" + y="25" + rx="0.068204239" + ry="0.065390877" /> + <rect + style="color:#000000;fill:#9b9b9b;fill-opacity:0.54970757;fill-rule:nonzero;stroke:none;stroke-width:1;marker:none;visibility:visible;display:block;overflow:visible" + id="rect15736-3" + width="22.000004" + height="1" + x="14.999992" + y="29" + rx="0.15156493" + ry="0.065390877" /> + <rect + style="color:#000000;fill:#9b9b9b;fill-opacity:0.54970757;fill-rule:nonzero;stroke:none;stroke-width:1;marker:none;visibility:visible;display:block;overflow:visible" + id="rect15738-9" + width="22.000004" + height="1" + x="14.999992" + y="31" + rx="0.15156493" + ry="0.065390877" /> + <rect + style="color:#000000;fill:#9b9b9b;fill-opacity:0.54970757;fill-rule:nonzero;stroke:none;stroke-width:1;marker:none;visibility:visible;display:block;overflow:visible" + id="rect15740-4" + width="22.000004" + height="1" + x="14.999992" + y="33" + rx="0.15156493" + ry="0.065390877" /> + <rect + style="color:#000000;fill:#9b9b9b;fill-opacity:0.54970757;fill-rule:nonzero;stroke:none;stroke-width:1;marker:none;visibility:visible;display:block;overflow:visible" + id="rect15742-8" + width="22.000004" + height="1" + x="14.999992" + y="35" + rx="0.15156493" + ry="0.065390877" /> + <rect + style="color:#000000;fill:#9b9b9b;fill-opacity:0.54970757;fill-rule:nonzero;stroke:none;stroke-width:1;marker:none;visibility:visible;display:block;overflow:visible" + id="rect15744-1" + width="15.400014" + height="1" + x="14.999992" + y="37" + rx="0.10609552" + ry="0.065390877" /> + </g> + </g> + </g> + </g> + <g + id="g4500-1-3" + transform="matrix(6.0278296,0,0,7.3216608,866.19057,610.01584)"> + <g + inkscape:label="Shadow" + id="layer6-7-0" /> + <g + id="layer1-7-2-4" + inkscape:label="Base" + style="display:inline" /> + <g + style="display:inline" + inkscape:label="Text" + id="layer5-7-4"> + <g + transform="matrix(0.388981,0,0,0.327274,-1.220361,0.172154)" + id="g3161-2-4"> + <path + sodipodi:type="arc" + style="opacity:0.7836257;color:#000000;fill:url(#radialGradient3195-8-2);fill-opacity:1;fill-rule:evenodd;stroke:none;stroke-width:2;marker:none;visibility:visible;display:inline;overflow:visible" + id="path3667-2-4" + sodipodi:cx="24.306795" + sodipodi:cy="42.07798" + sodipodi:rx="15.821514" + sodipodi:ry="4.5078058" + d="m 40.128309,42.07798 c 0,2.489592 -7.083533,4.507806 -15.821514,4.507806 -8.737981,0 -15.821514,-2.018214 -15.821514,-4.507806 0,-2.489592 7.083533,-4.507806 15.821514,-4.507806 8.737981,0 15.821514,2.018214 15.821514,4.507806 z" + transform="translate(0,0.707108)" /> + <rect + style="color:#000000;fill:url(#radialGradient3197-4-0);fill-opacity:1;fill-rule:nonzero;stroke:url(#radialGradient3199-9-0);stroke-width:1;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-opacity:1;stroke-dashoffset:0;marker:none;visibility:visible;display:block;overflow:visible" + id="rect15391-6-7" + width="34.875" + height="40.920494" + x="6.6035528" + y="3.6464462" + ry="1.1490486" /> + <rect + style="color:#000000;fill:none;stroke:url(#radialGradient3201-8-8);stroke-width:1;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-opacity:1;stroke-dashoffset:0;marker:none;visibility:visible;display:block;overflow:visible" + id="rect15660-1-6" + width="32.775887" + height="38.946384" + x="7.6660538" + y="4.5839462" + ry="0.14904857" + rx="0.14904857" /> + <g + style="display:inline" + transform="translate(0.646447,-0.03798933)" + id="g2270-0-3"> + <g + id="g1440-6-1" + style="fill:#ffffff;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-miterlimit:4" + transform="matrix(0.229703,0,0,0.229703,4.967081,4.244972)"> + <radialGradient + id="radialGradient1442-1-7" + cx="20.892099" + cy="114.5684" + r="5.256" + fx="20.892099" + fy="114.5684" + gradientUnits="userSpaceOnUse"> + <stop + offset="0" + style="stop-color:#F0F0F0" + id="stop1444-5-5" /> + <stop + offset="1" + style="stop-color:#474747" + id="stop1446-9-9" /> + </radialGradient> + <path + style="stroke:none" + d="m 23.428,113.07 c 0,1.973 -1.6,3.572 -3.573,3.572 -1.974,0 -3.573,-1.6 -3.573,-3.572 0,-1.974 1.6,-3.573 3.573,-3.573 1.973,0 3.573,1.6 3.573,3.573 z" + id="path1448-4-6" + inkscape:connector-curvature="0" /> + <radialGradient + id="radialGradient1450-9-2" + cx="20.892099" + cy="64.567902" + r="5.257" + fx="20.892099" + fy="64.567902" + gradientUnits="userSpaceOnUse"> + <stop + offset="0" + style="stop-color:#F0F0F0" + id="stop1452-0-1" /> + <stop + offset="1" + style="stop-color:#474747" + id="stop1454-9-7" /> + </radialGradient> + <path + style="stroke:none" + d="m 23.428,63.07 c 0,1.973 -1.6,3.573 -3.573,3.573 -1.974,0 -3.573,-1.6 -3.573,-3.573 0,-1.974 1.6,-3.573 3.573,-3.573 1.973,0 3.573,1.6 3.573,3.573 z" + id="path1456-1-8" + inkscape:connector-curvature="0" /> + </g> + <path + style="fill:url(#radialGradient3203-6-1);fill-rule:nonzero;stroke:none" + d="m 9.9950109,29.952326 c 0,0.453204 -0.3675248,0.820499 -0.8207288,0.820499 -0.4534338,0 -0.8207289,-0.367524 -0.8207289,-0.820499 0,-0.453434 0.3675248,-0.820729 0.8207289,-0.820729 0.453204,0 0.8207288,0.367525 0.8207288,0.820729 z" + id="path15570-7-5" + inkscape:connector-curvature="0" /> + <path + style="fill:url(#radialGradient3205-0-4);fill-rule:nonzero;stroke:none" + d="m 9.9950109,18.467176 c 0,0.453204 -0.3675248,0.820729 -0.8207288,0.820729 -0.4534338,0 -0.8207289,-0.367525 -0.8207289,-0.820729 0,-0.453434 0.3675248,-0.820729 0.8207289,-0.820729 0.453204,0 0.8207288,0.367525 0.8207288,0.820729 z" + id="path15577-7-7" + inkscape:connector-curvature="0" /> + </g> + <path + style="fill:none;stroke:#000000;stroke-width:0.98855311;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:0.01754384;display:inline" + d="m 11.505723,5.4942766 0,37.9065924" + id="path15672-1-4" + sodipodi:nodetypes="cc" + inkscape:connector-curvature="0" /> + <path + style="fill:none;stroke:#ffffff;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:0.20467828;display:inline" + d="m 12.5,5.0205154 0,38.0177126" + id="path15674-1-1" + sodipodi:nodetypes="cc" + inkscape:connector-curvature="0" /> + <g + transform="matrix(0.909091,0,0,1,2.363628,0)" + id="g2253-5-8"> + <rect + style="color:#000000;fill:#9b9b9b;fill-opacity:0.54970757;fill-rule:nonzero;stroke:none;stroke-width:1;marker:none;visibility:visible;display:block;overflow:visible" + id="rect15686-9-5" + width="22.000004" + height="1" + x="15.000002" + y="9" + rx="0.15156493" + ry="0.065390877" /> + <rect + style="color:#000000;fill:#9b9b9b;fill-opacity:0.54970757;fill-rule:nonzero;stroke:none;stroke-width:1;marker:none;visibility:visible;display:block;overflow:visible" + id="rect15688-7-9" + width="22.000004" + height="1" + x="15.000002" + y="11" + rx="0.15156493" + ry="0.065390877" /> + <rect + style="color:#000000;fill:#9b9b9b;fill-opacity:0.54970757;fill-rule:nonzero;stroke:none;stroke-width:1;marker:none;visibility:visible;display:block;overflow:visible" + id="rect15690-7-7" + width="22.000004" + height="1" + x="15.000002" + y="13" + rx="0.15156493" + ry="0.065390877" /> + <rect + style="color:#000000;fill:#9b9b9b;fill-opacity:0.54970757;fill-rule:nonzero;stroke:none;stroke-width:1;marker:none;visibility:visible;display:block;overflow:visible" + id="rect15692-6-5" + width="22.000004" + height="1" + x="15.000002" + y="15" + rx="0.15156493" + ry="0.065390877" /> + <rect + style="color:#000000;fill:#9b9b9b;fill-opacity:0.54970757;fill-rule:nonzero;stroke:none;stroke-width:1;marker:none;visibility:visible;display:block;overflow:visible" + id="rect15694-7-3" + width="22.000004" + height="1" + x="15.000002" + y="17" + rx="0.15156493" + ry="0.065390877" /> + <rect + style="color:#000000;fill:#9b9b9b;fill-opacity:0.54970757;fill-rule:nonzero;stroke:none;stroke-width:1;marker:none;visibility:visible;display:block;overflow:visible" + id="rect15696-3-8" + width="22.000004" + height="1" + x="15.000002" + y="19" + rx="0.15156493" + ry="0.065390877" /> + <rect + style="color:#000000;fill:#9b9b9b;fill-opacity:0.54970757;fill-rule:nonzero;stroke:none;stroke-width:1;marker:none;visibility:visible;display:block;overflow:visible" + id="rect15698-6-8" + width="22.000004" + height="1" + x="15.000002" + y="21" + rx="0.15156493" + ry="0.065390877" /> + <rect + style="color:#000000;fill:#9b9b9b;fill-opacity:0.54970757;fill-rule:nonzero;stroke:none;stroke-width:1;marker:none;visibility:visible;display:block;overflow:visible" + id="rect15700-5-3" + width="22.000004" + height="1" + x="15.000002" + y="23" + rx="0.15156493" + ry="0.065390877" /> + <rect + style="color:#000000;fill:#9b9b9b;fill-opacity:0.54970757;fill-rule:nonzero;stroke:none;stroke-width:1;marker:none;visibility:visible;display:block;overflow:visible" + id="rect15732-6-1" + width="9.9000053" + height="1" + x="14.999992" + y="25" + rx="0.068204239" + ry="0.065390877" /> + <rect + style="color:#000000;fill:#9b9b9b;fill-opacity:0.54970757;fill-rule:nonzero;stroke:none;stroke-width:1;marker:none;visibility:visible;display:block;overflow:visible" + id="rect15736-3-8" + width="22.000004" + height="1" + x="14.999992" + y="29" + rx="0.15156493" + ry="0.065390877" /> + <rect + style="color:#000000;fill:#9b9b9b;fill-opacity:0.54970757;fill-rule:nonzero;stroke:none;stroke-width:1;marker:none;visibility:visible;display:block;overflow:visible" + id="rect15738-9-9" + width="22.000004" + height="1" + x="14.999992" + y="31" + rx="0.15156493" + ry="0.065390877" /> + <rect + style="color:#000000;fill:#9b9b9b;fill-opacity:0.54970757;fill-rule:nonzero;stroke:none;stroke-width:1;marker:none;visibility:visible;display:block;overflow:visible" + id="rect15740-4-6" + width="22.000004" + height="1" + x="14.999992" + y="33" + rx="0.15156493" + ry="0.065390877" /> + <rect + style="color:#000000;fill:#9b9b9b;fill-opacity:0.54970757;fill-rule:nonzero;stroke:none;stroke-width:1;marker:none;visibility:visible;display:block;overflow:visible" + id="rect15742-8-4" + width="22.000004" + height="1" + x="14.999992" + y="35" + rx="0.15156493" + ry="0.065390877" /> + <rect + style="color:#000000;fill:#9b9b9b;fill-opacity:0.54970757;fill-rule:nonzero;stroke:none;stroke-width:1;marker:none;visibility:visible;display:block;overflow:visible" + id="rect15744-1-3" + width="15.400014" + height="1" + x="14.999992" + y="37" + rx="0.10609552" + ry="0.065390877" /> + </g> + </g> + </g> + </g> + <g + id="g4500-1-3-9" + transform="matrix(6.0278296,0,0,7.3216608,899.61914,584.01585)"> + <g + inkscape:label="Shadow" + id="layer6-7-0-4" /> + <g + id="layer1-7-2-4-6" + inkscape:label="Base" + style="display:inline" /> + <g + style="display:inline" + inkscape:label="Text" + id="layer5-7-4-9"> + <g + transform="matrix(0.388981,0,0,0.327274,-1.220361,0.172154)" + id="g3161-2-4-2"> + <path + sodipodi:type="arc" + style="opacity:0.7836257;color:#000000;fill:url(#radialGradient3195-8-2-3);fill-opacity:1;fill-rule:evenodd;stroke:none;stroke-width:2;marker:none;visibility:visible;display:inline;overflow:visible" + id="path3667-2-4-2" + sodipodi:cx="24.306795" + sodipodi:cy="42.07798" + sodipodi:rx="15.821514" + sodipodi:ry="4.5078058" + d="m 40.128309,42.07798 c 0,2.489592 -7.083533,4.507806 -15.821514,4.507806 -8.737981,0 -15.821514,-2.018214 -15.821514,-4.507806 0,-2.489592 7.083533,-4.507806 15.821514,-4.507806 8.737981,0 15.821514,2.018214 15.821514,4.507806 z" + transform="translate(0,0.707108)" /> + <rect + style="color:#000000;fill:url(#radialGradient3197-4-0-0);fill-opacity:1;fill-rule:nonzero;stroke:url(#radialGradient3199-9-0-8);stroke-width:1;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-opacity:1;stroke-dashoffset:0;marker:none;visibility:visible;display:block;overflow:visible" + id="rect15391-6-7-4" + width="34.875" + height="40.920494" + x="6.6035528" + y="3.6464462" + ry="1.1490486" /> + <rect + style="color:#000000;fill:none;stroke:url(#radialGradient3201-8-8-6);stroke-width:1;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-opacity:1;stroke-dashoffset:0;marker:none;visibility:visible;display:block;overflow:visible" + id="rect15660-1-6-7" + width="32.775887" + height="38.946384" + x="7.6660538" + y="4.5839462" + ry="0.14904857" + rx="0.14904857" /> + <g + style="display:inline" + transform="translate(0.646447,-0.03798933)" + id="g2270-0-3-7"> + <g + id="g1440-6-1-5" + style="fill:#ffffff;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-miterlimit:4" + transform="matrix(0.229703,0,0,0.229703,4.967081,4.244972)"> + <radialGradient + id="radialGradient1442-1-7-4" + cx="20.892099" + cy="114.5684" + r="5.256" + fx="20.892099" + fy="114.5684" + gradientUnits="userSpaceOnUse"> + <stop + offset="0" + style="stop-color:#F0F0F0" + id="stop1444-5-5-8" /> + <stop + offset="1" + style="stop-color:#474747" + id="stop1446-9-9-1" /> + </radialGradient> + <path + style="stroke:none" + d="m 23.428,113.07 c 0,1.973 -1.6,3.572 -3.573,3.572 -1.974,0 -3.573,-1.6 -3.573,-3.572 0,-1.974 1.6,-3.573 3.573,-3.573 1.973,0 3.573,1.6 3.573,3.573 z" + id="path1448-4-6-2" + inkscape:connector-curvature="0" /> + <radialGradient + id="radialGradient1450-9-2-8" + cx="20.892099" + cy="64.567902" + r="5.257" + fx="20.892099" + fy="64.567902" + gradientUnits="userSpaceOnUse"> + <stop + offset="0" + style="stop-color:#F0F0F0" + id="stop1452-0-1-9" /> + <stop + offset="1" + style="stop-color:#474747" + id="stop1454-9-7-3" /> + </radialGradient> + <path + style="stroke:none" + d="m 23.428,63.07 c 0,1.973 -1.6,3.573 -3.573,3.573 -1.974,0 -3.573,-1.6 -3.573,-3.573 0,-1.974 1.6,-3.573 3.573,-3.573 1.973,0 3.573,1.6 3.573,3.573 z" + id="path1456-1-8-6" + inkscape:connector-curvature="0" /> + </g> + <path + style="fill:url(#radialGradient3203-6-1-3);fill-rule:nonzero;stroke:none" + d="m 9.9950109,29.952326 c 0,0.453204 -0.3675248,0.820499 -0.8207288,0.820499 -0.4534338,0 -0.8207289,-0.367524 -0.8207289,-0.820499 0,-0.453434 0.3675248,-0.820729 0.8207289,-0.820729 0.453204,0 0.8207288,0.367525 0.8207288,0.820729 z" + id="path15570-7-5-8" + inkscape:connector-curvature="0" /> + <path + style="fill:url(#radialGradient3205-0-4-5);fill-rule:nonzero;stroke:none" + d="m 9.9950109,18.467176 c 0,0.453204 -0.3675248,0.820729 -0.8207288,0.820729 -0.4534338,0 -0.8207289,-0.367525 -0.8207289,-0.820729 0,-0.453434 0.3675248,-0.820729 0.8207289,-0.820729 0.453204,0 0.8207288,0.367525 0.8207288,0.820729 z" + id="path15577-7-7-0" + inkscape:connector-curvature="0" /> + </g> + <path + style="fill:none;stroke:#000000;stroke-width:0.98855311;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:0.01754384;display:inline" + d="m 11.505723,5.4942766 0,37.9065924" + id="path15672-1-4-2" + sodipodi:nodetypes="cc" + inkscape:connector-curvature="0" /> + <path + style="fill:none;stroke:#ffffff;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:0.20467828;display:inline" + d="m 12.5,5.0205154 0,38.0177126" + id="path15674-1-1-1" + sodipodi:nodetypes="cc" + inkscape:connector-curvature="0" /> + <g + transform="matrix(0.909091,0,0,1,2.363628,0)" + id="g2253-5-8-0"> + <rect + style="color:#000000;fill:#9b9b9b;fill-opacity:0.54970757;fill-rule:nonzero;stroke:none;stroke-width:1;marker:none;visibility:visible;display:block;overflow:visible" + id="rect15686-9-5-5" + width="22.000004" + height="1" + x="15.000002" + y="9" + rx="0.15156493" + ry="0.065390877" /> + <rect + style="color:#000000;fill:#9b9b9b;fill-opacity:0.54970757;fill-rule:nonzero;stroke:none;stroke-width:1;marker:none;visibility:visible;display:block;overflow:visible" + id="rect15688-7-9-1" + width="22.000004" + height="1" + x="15.000002" + y="11" + rx="0.15156493" + ry="0.065390877" /> + <rect + style="color:#000000;fill:#9b9b9b;fill-opacity:0.54970757;fill-rule:nonzero;stroke:none;stroke-width:1;marker:none;visibility:visible;display:block;overflow:visible" + id="rect15690-7-7-1" + width="22.000004" + height="1" + x="15.000002" + y="13" + rx="0.15156493" + ry="0.065390877" /> + <rect + style="color:#000000;fill:#9b9b9b;fill-opacity:0.54970757;fill-rule:nonzero;stroke:none;stroke-width:1;marker:none;visibility:visible;display:block;overflow:visible" + id="rect15692-6-5-0" + width="22.000004" + height="1" + x="15.000002" + y="15" + rx="0.15156493" + ry="0.065390877" /> + <rect + style="color:#000000;fill:#9b9b9b;fill-opacity:0.54970757;fill-rule:nonzero;stroke:none;stroke-width:1;marker:none;visibility:visible;display:block;overflow:visible" + id="rect15694-7-3-8" + width="22.000004" + height="1" + x="15.000002" + y="17" + rx="0.15156493" + ry="0.065390877" /> + <rect + style="color:#000000;fill:#9b9b9b;fill-opacity:0.54970757;fill-rule:nonzero;stroke:none;stroke-width:1;marker:none;visibility:visible;display:block;overflow:visible" + id="rect15696-3-8-5" + width="22.000004" + height="1" + x="15.000002" + y="19" + rx="0.15156493" + ry="0.065390877" /> + <rect + style="color:#000000;fill:#9b9b9b;fill-opacity:0.54970757;fill-rule:nonzero;stroke:none;stroke-width:1;marker:none;visibility:visible;display:block;overflow:visible" + id="rect15698-6-8-0" + width="22.000004" + height="1" + x="15.000002" + y="21" + rx="0.15156493" + ry="0.065390877" /> + <rect + style="color:#000000;fill:#9b9b9b;fill-opacity:0.54970757;fill-rule:nonzero;stroke:none;stroke-width:1;marker:none;visibility:visible;display:block;overflow:visible" + id="rect15700-5-3-6" + width="22.000004" + height="1" + x="15.000002" + y="23" + rx="0.15156493" + ry="0.065390877" /> + <rect + style="color:#000000;fill:#9b9b9b;fill-opacity:0.54970757;fill-rule:nonzero;stroke:none;stroke-width:1;marker:none;visibility:visible;display:block;overflow:visible" + id="rect15732-6-1-4" + width="9.9000053" + height="1" + x="14.999992" + y="25" + rx="0.068204239" + ry="0.065390877" /> + <rect + style="color:#000000;fill:#9b9b9b;fill-opacity:0.54970757;fill-rule:nonzero;stroke:none;stroke-width:1;marker:none;visibility:visible;display:block;overflow:visible" + id="rect15736-3-8-6" + width="22.000004" + height="1" + x="14.999992" + y="29" + rx="0.15156493" + ry="0.065390877" /> + <rect + style="color:#000000;fill:#9b9b9b;fill-opacity:0.54970757;fill-rule:nonzero;stroke:none;stroke-width:1;marker:none;visibility:visible;display:block;overflow:visible" + id="rect15738-9-9-2" + width="22.000004" + height="1" + x="14.999992" + y="31" + rx="0.15156493" + ry="0.065390877" /> + <rect + style="color:#000000;fill:#9b9b9b;fill-opacity:0.54970757;fill-rule:nonzero;stroke:none;stroke-width:1;marker:none;visibility:visible;display:block;overflow:visible" + id="rect15740-4-6-5" + width="22.000004" + height="1" + x="14.999992" + y="33" + rx="0.15156493" + ry="0.065390877" /> + <rect + style="color:#000000;fill:#9b9b9b;fill-opacity:0.54970757;fill-rule:nonzero;stroke:none;stroke-width:1;marker:none;visibility:visible;display:block;overflow:visible" + id="rect15742-8-4-8" + width="22.000004" + height="1" + x="14.999992" + y="35" + rx="0.15156493" + ry="0.065390877" /> + <rect + style="color:#000000;fill:#9b9b9b;fill-opacity:0.54970757;fill-rule:nonzero;stroke:none;stroke-width:1;marker:none;visibility:visible;display:block;overflow:visible" + id="rect15744-1-3-6" + width="15.400014" + height="1" + x="14.999992" + y="37" + rx="0.10609552" + ry="0.065390877" /> + </g> + </g> + </g> + </g> + <g + id="layer1-3" + inkscape:label="Layer 1" + transform="matrix(5.9350697,0,0,5.5679597,867.91807,625.30765)"> + <g + transform="matrix(1,0,0,0.9887078,0,0.2484274)" + id="g3213"> + <path + transform="matrix(0.6655116,0,0,0.7692168,-5.0588175,-10.231117)" + d="m 40.65864,37.967922 c 0,2.172292 -7.400116,3.933282 -16.528622,3.933282 -9.128505,0 -16.5286214,-1.76099 -16.5286214,-3.933282 0,-2.172291 7.4001164,-3.933281 16.5286214,-3.933281 9.128506,0 16.528622,1.76099 16.528622,3.933281 z" + sodipodi:ry="3.9332814" + sodipodi:rx="16.528622" + sodipodi:cy="37.967922" + sodipodi:cx="24.130018" + id="path4475" + style="opacity:0.17112301;fill:url(#radialGradient3224);fill-opacity:1;fill-rule:evenodd;stroke:none;stroke-width:1;marker:none;visibility:visible;display:inline;overflow:visible" + sodipodi:type="arc" /> + <path + style="fill:#dcdcdc;fill-opacity:1;fill-rule:evenodd;stroke:url(#linearGradient3226);stroke-width:0.96507967;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:10;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0;marker:none;visibility:visible;display:inline;overflow:visible" + d="m 8.5612859,0.34327135 c -3.7448625,0 -6.7841713,3.34291215 -6.7841713,7.46185735 0,4.1189453 3.0393088,7.4618573 6.7841713,7.4618573 1.6009641,0 3.0141551,-0.700595 4.1748741,-1.721967 -0.0945,0.509549 -0.0359,1.030033 0.347907,1.396707 l 5.044641,4.821508 c 0.567502,0.542164 1.420559,0.471128 1.913484,-0.153064 0.492924,-0.624192 0.42834,-1.562462 -0.139163,-2.104626 l -5.04464,-4.821508 c -0.308974,-0.295179 -0.686882,-0.382571 -1.061114,-0.325261 0.914092,-1.271454 1.548182,-2.8080659 1.548182,-4.5536463 0,-4.1189452 -3.039309,-7.46185735 -6.7841711,-7.46185735 z m -0.034791,0.6205309 c 3.5149611,0 6.1156251,2.42352985 6.1156251,6.72652865 0,4.3901881 -2.676294,6.7265291 -6.1156251,6.7265291 -3.3601307,0 -6.1156247,-2.772282 -6.1156247,-6.7265291 0,-4.040493 2.6799511,-6.7265287 6.1156247,-6.72652865 z" + id="path2844" + sodipodi:nodetypes="csscccscccscczzzz" + inkscape:connector-curvature="0" /> + <path + id="path4430" + d="m 8.5499378,0.31128806 c -3.7569679,0 -6.8061015,3.35371814 -6.8061015,7.48597784 0,4.1322601 3.0491336,7.4859781 6.8061015,7.4859781 1.6061392,0 3.0238982,-0.70286 4.1883702,-1.727533 -0.0948,0.511196 -0.03602,1.033362 0.349031,1.401221 l 5.060947,4.837093 c 0.569337,0.543917 1.425152,0.472652 1.91967,-0.153558 0.494518,-0.626209 0.429724,-1.567513 -0.139612,-2.111429 l -5.060948,-4.837094 c -0.309972,-0.296132 -0.689102,-0.383808 -1.064544,-0.326312 0.917047,-1.275564 1.553187,-2.817143 1.553187,-4.5683661 0,-4.1322597 -3.049133,-7.48597784 -6.8061012,-7.48597784 z M 8.5150347,1.9236525 c 2.8899753,1e-7 5.2354623,2.5797832 5.2354623,5.7584447 0,3.1786618 -2.345487,5.7584438 -5.2354623,5.7584438 -2.8899755,0 -5.2354627,-2.579782 -5.2354627,-5.7584438 1e-7,-3.1786615 2.3454872,-5.7584447 5.2354627,-5.7584447 z" + style="fill:#dcdcdc;fill-opacity:1;fill-rule:evenodd;stroke:none;stroke-width:1.00000036;marker:none;visibility:visible;display:inline;overflow:visible" + inkscape:connector-curvature="0" /> + <path + sodipodi:nodetypes="ccccc" + id="path4438" + d="m 18.168039,19.793519 c -0.22024,-1.150385 0.64292,-2.434902 1.649045,-2.423239 0,0 -4.95091,-4.685224 -4.95091,-4.685224 -1.354916,-0.0287 -1.964423,1.150096 -1.737735,2.327869 l 5.0396,4.780594 z" + style="fill:url(#linearGradient3228);fill-opacity:1;fill-rule:evenodd;stroke:none;stroke-width:1;marker:none;visibility:visible;display:inline;overflow:visible" + inkscape:connector-curvature="0" /> + <path + transform="matrix(0.5731738,0,0,0.6304294,-1.5853926,-4.3735706)" + d="m 28.549437,18.920233 c 0,6.101942 -4.946602,11.048544 -11.048544,11.048544 -6.101943,0 -11.0485443,-4.946602 -11.0485443,-11.048544 0,-6.101943 4.9466013,-11.0485442 11.0485443,-11.0485442 6.101942,0 11.048544,4.9466012 11.048544,11.0485442 z" + sodipodi:ry="11.048544" + sodipodi:rx="11.048544" + sodipodi:cy="18.920233" + sodipodi:cx="17.500893" + id="path4450" + style="fill:none;stroke:url(#linearGradient3230);stroke-width:0.8027336;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:10;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0;marker:none;visibility:visible;display:inline;overflow:visible" + sodipodi:type="arc" /> + <path + sodipodi:type="arc" + style="fill:url(#radialGradient3232);fill-opacity:1;fill-rule:evenodd;stroke:none;stroke-width:1;marker:none;visibility:visible;display:inline;overflow:visible" + id="path4485" + sodipodi:cx="24.130018" + sodipodi:cy="37.967922" + sodipodi:rx="16.528622" + sodipodi:ry="3.9332814" + d="m 40.65864,37.967922 c 0,2.172292 -7.400116,3.933282 -16.528622,3.933282 -9.128505,0 -16.5286214,-1.76099 -16.5286214,-3.933282 0,-2.172291 7.4001164,-3.933281 16.5286214,-3.933281 9.128506,0 16.528622,1.76099 16.528622,3.933281 z" + transform="matrix(0.2290242,0,0,0.3085091,4.1194028,6.6568292)" /> + <rect + transform="matrix(0.7209552,0.6929817,-0.6127617,0.7902677,0,0)" + ry="0.91988331" + rx="1.0267676" + y="-0.82936758" + x="18.625082" + height="2.1635909" + width="9.1536846" + id="rect4495" + style="opacity:0.43315507;fill:none;stroke:#ffffff;stroke-width:0.48389873;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:10;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0;marker:none;visibility:visible;display:inline;overflow:visible" /> + <path + transform="matrix(0.6435107,0,0,0.7077924,-2.8732256,-5.4474068)" + d="m 25.897786,18.478292 c 0,4.588661 -3.719844,8.308506 -8.308505,8.308506 -4.588661,0 -8.308505,-3.719845 -8.308505,-8.308506 0,-4.58866 3.719844,-8.308505 8.308505,-8.308505 4.588661,0 8.308505,3.719845 8.308505,8.308505 z" + sodipodi:ry="8.3085051" + sodipodi:rx="8.3085051" + sodipodi:cy="18.478292" + sodipodi:cx="17.589281" + id="path4452" + style="fill:url(#radialGradient3234);fill-opacity:1;fill-rule:evenodd;stroke:#093288;stroke-width:0.71499395;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:10;stroke-opacity:1;stroke-dashoffset:0;marker:none;visibility:visible" + sodipodi:type="arc" /> + <path + id="path4462" + d="M 8.599769,2.0802586 C 6.0222861,1.9592439 3.832837,3.7642898 3.7065327,6.1143856 3.6700554,6.7931036 3.8445229,7.4273551 4.1241764,8.0114996 4.7328427,8.2489207 5.3836918,8.4215706 6.0825624,8.4543832 9.1368601,8.5977848 11.694035,6.5183369 12.029878,3.7854215 11.222754,2.822084 10.028909,2.1473578 8.599769,2.0802586 z" + style="opacity:0.40248964;fill:url(#radialGradient3236);fill-opacity:1;fill-rule:evenodd;stroke:none;stroke-width:1;marker:none;visibility:visible;display:inline;overflow:visible" + inkscape:connector-curvature="0" /> + </g> + </g> + <path + sodipodi:nodetypes="cccccccccccccccc" + id="path853-1" + d="m 464.23207,653.04219 c -34.40454,-1.53163 -90.63387,-41.71387 -85.64033,-70.26908 6.67877,-35.80898 42.87928,-56.14669 75.76112,-34.92309 -21.84275,-19.61883 -46.08051,-72.07973 13.91159,-108.99955 45.25043,-23.84757 83.22642,24.41021 82.095,40.65256 -9.21279,-29.75938 57.66336,-113.47326 102.62959,-84.87137 46.80339,36.24004 17.31616,135.11373 -15.91395,143.16054 48.11614,-14.8819 73.56575,88.22109 5.14343,98.78365 31.12639,-11.18088 76.84163,59.18596 69.11249,96.05785 -6.80494,45.87748 -53.47616,45.87135 -68.26068,42.25172 10.10803,33.50757 30.40849,85.45334 -9.98582,114.19371 -39.06863,21.29904 -87.01923,16.89488 -104.87548,-2.61617 -17.35187,-21.50291 -20.49471,-46.83332 -1.59692,-78.99566 -15.53749,25.58341 -79.37443,18.32339 -96.49679,-3.52328 -19.46083,-24.90454 -27.36788,-56.62111 -24.2976,-86.28737 1.1457,-24.28379 20.548,-64.75524 58.41433,-64.61446 z" + style="opacity:0.153;fill:#1c2bb1;fill-opacity:1;fill-rule:evenodd;stroke:none;filter:url(#filter6431)" + inkscape:connector-curvature="0" /> + <path + sodipodi:nodetypes="cccccccccccccccc" + id="path853" + d="m 454.6058,645.64132 c -34.40454,-1.53163 -90.63387,-41.71387 -85.64033,-70.26908 6.67877,-35.80898 42.87928,-56.14669 75.76112,-34.92309 -21.84275,-19.61883 -46.08051,-72.07973 13.91159,-108.99955 45.25043,-23.84757 83.22642,24.41021 82.095,40.65256 -9.21279,-29.75938 57.66336,-113.47326 102.62959,-84.87137 46.80339,36.24004 17.31616,135.11373 -15.91395,143.16054 48.11614,-14.8819 73.56575,88.22109 5.14343,98.78365 31.12639,-11.18088 76.84163,59.18596 69.11249,96.05785 -6.80494,45.87748 -53.47616,45.87135 -68.26068,42.25172 10.10803,33.50757 30.40849,85.45334 -9.98582,114.19371 -39.06863,21.29904 -87.01923,16.89488 -104.87548,-2.61617 -17.35187,-21.50291 -20.49471,-46.83332 -1.59692,-78.99566 -15.53749,25.58341 -79.37443,18.32339 -96.49679,-3.52328 -19.46083,-24.90454 -27.36788,-56.62111 -24.2976,-86.28737 1.1457,-24.28379 20.548,-64.75524 58.41433,-64.61446 z" + style="fill:url(#linearGradient854);fill-rule:evenodd;stroke:#000000;stroke-width:3.42814374;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none" + inkscape:connector-curvature="0" /> + <g + id="g5722" + transform="translate(-381.08637,-43.436559)"> + <path + inkscape:connector-curvature="0" + id="path5647-1" + d="m 669.99529,844.65261 c 83.15229,-83.1523 83.15229,-83.1523 83.15229,-83.1523" + style="opacity:0.90000006;fill:none;stroke:#030000;stroke-width:5;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" /> + <path + inkscape:connector-curvature="0" + id="path5649-2" + d="m 753.88771,760.96455 c 0,16.66751 0,16.66751 0,16.66751" + style="opacity:0.90000006;fill:none;stroke:#030000;stroke-width:5;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" /> + <path + inkscape:connector-curvature="0" + id="path5649-8-9" + d="m 753.78309,760.84726 c -16.6675,0 -16.6675,0 -16.6675,0" + style="opacity:0.90000006;fill:none;stroke:#030000;stroke-width:5;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" /> + </g> + <g + id="g5757" + transform="translate(-598.83517,-151.25004)"> + <path + inkscape:connector-curvature="0" + id="path5647-8" + d="M 802.29517,742.83264 C 942.84625,777.0538 942.84625,777.0538 942.84625,777.0538" + style="opacity:0.90000006;fill:none;stroke:#030000;stroke-width:5;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" /> + <path + inkscape:connector-curvature="0" + id="path5649-0" + d="M 942.20503,775.99548 C 932.40327,762.5147 932.40327,762.5147 932.40327,762.5147" + style="opacity:0.90000006;fill:none;stroke:#030000;stroke-width:5;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" /> + <path + inkscape:connector-curvature="0" + id="path5649-8-92" + d="m 942.18939,778.15187 c -13.48077,9.80175 -13.48077,9.80175 -13.48077,9.80175" + style="opacity:0.90000006;fill:none;stroke:#030000;stroke-width:5;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" /> + </g> + <g + id="g5915" + transform="translate(-68,0)"> + <path + inkscape:connector-curvature="0" + id="path5647-1-1" + d="m 250.24339,924.91621 c -1e-5,-117.59511 -1e-5,-117.59511 -1e-5,-117.59511" + style="fill:none;stroke:#ffffff;stroke-width:5;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" /> + <path + inkscape:connector-curvature="0" + id="path5647-1-1-4" + d="m 225.79828,952.17492 c -1e-5,-145.09639 -1e-5,-145.09639 -1e-5,-145.09639" + style="fill:none;stroke:#ffffff;stroke-width:5;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" /> + <g + transform="translate(-4,0)" + id="g5834"> + <path + style="fill:none;stroke:#ffffff;stroke-width:5;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" + d="m 254.29713,807.35861 c 7.63347,8.13855 7.63347,8.13855 7.63347,8.13855" + id="path5649-2-8" + inkscape:connector-curvature="0" /> + <path + style="fill:none;stroke:#ffffff;stroke-width:5;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" + d="m 254.18314,807.10607 c -7.63347,8.13855 -7.63347,8.13855 -7.63347,8.13855" + id="path5649-2-8-1" + inkscape:connector-curvature="0" /> + </g> + <g + id="g5834-6" + transform="translate(-28.378807,-0.1262667)"> + <path + style="fill:none;stroke:#ffffff;stroke-width:5;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" + d="m 254.29713,807.35861 c 7.63347,8.13855 7.63347,8.13855 7.63347,8.13855" + id="path5649-2-8-3" + inkscape:connector-curvature="0" /> + <path + style="fill:none;stroke:#ffffff;stroke-width:5;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" + d="m 254.18314,807.10607 c -7.63347,8.13855 -7.63347,8.13855 -7.63347,8.13855" + id="path5649-2-8-1-8" + inkscape:connector-curvature="0" /> + </g> + <path + inkscape:connector-curvature="0" + id="path5647-1-1-5" + d="m 275.07468,902.4815 c -10e-6,-95.09507 -10e-6,-95.09507 -10e-6,-95.09507" + style="fill:none;stroke:#ffffff;stroke-width:5;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" /> + <g + transform="translate(20.83129,0.06533)" + id="g5834-5"> + <path + style="fill:none;stroke:#ffffff;stroke-width:5;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" + d="m 254.29713,807.35861 c 7.63347,8.13855 7.63347,8.13855 7.63347,8.13855" + id="path5649-2-8-0" + inkscape:connector-curvature="0" /> + <path + style="fill:none;stroke:#ffffff;stroke-width:5;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" + d="m 254.18314,807.10607 c -7.63347,8.13855 -7.63347,8.13855 -7.63347,8.13855" + id="path5649-2-8-1-1" + inkscape:connector-curvature="0" /> + </g> + <path + inkscape:connector-curvature="0" + id="path5647-1-1-2" + d="m 300.24339,877.05907 c -10e-6,-69.73797 -10e-6,-69.73797 -10e-6,-69.73797" + style="fill:none;stroke:#ffffff;stroke-width:5;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" /> + <g + transform="translate(46,2.3999999e-6)" + id="g5834-64"> + <path + style="fill:none;stroke:#ffffff;stroke-width:5;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" + d="m 254.29713,807.35861 c 7.63347,8.13855 7.63347,8.13855 7.63347,8.13855" + id="path5649-2-8-8" + inkscape:connector-curvature="0" /> + <path + style="fill:none;stroke:#ffffff;stroke-width:5;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" + d="m 254.18314,807.10607 c -7.63347,8.13855 -7.63347,8.13855 -7.63347,8.13855" + id="path5649-2-8-1-5" + inkscape:connector-curvature="0" /> + </g> + <path + inkscape:connector-curvature="0" + id="path5647-1-1-6" + d="m 326.24339,852.41621 c -10e-6,-45.09511 -10e-6,-45.09511 -10e-6,-45.09511" + style="fill:none;stroke:#ffffff;stroke-width:5;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" /> + <g + transform="translate(72,2.3999999e-6)" + id="g5834-2"> + <path + style="fill:none;stroke:#ffffff;stroke-width:5;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" + d="m 254.29713,807.35861 c 7.63347,8.13855 7.63347,8.13855 7.63347,8.13855" + id="path5649-2-8-5" + inkscape:connector-curvature="0" /> + <path + style="fill:none;stroke:#ffffff;stroke-width:5;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" + d="m 254.18314,807.10607 c -7.63347,8.13855 -7.63347,8.13855 -7.63347,8.13855" + id="path5649-2-8-1-2" + inkscape:connector-curvature="0" /> + </g> + </g> + <g + transform="translate(-154.9793,-208.42947)" + id="g5915-6"> + <path + inkscape:connector-curvature="0" + id="path5647-1-1-9" + d="m 250.24339,924.91621 c -1e-5,-117.59511 -1e-5,-117.59511 -1e-5,-117.59511" + style="fill:none;stroke:#ffffff;stroke-width:5;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" /> + <path + inkscape:connector-curvature="0" + id="path5647-1-1-4-1" + d="m 225.79828,952.17492 c -1e-5,-145.09639 -1e-5,-145.09639 -1e-5,-145.09639" + style="fill:none;stroke:#ffffff;stroke-width:5;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" /> + <g + transform="translate(-4,0)" + id="g5834-3"> + <path + style="fill:none;stroke:#ffffff;stroke-width:5;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" + d="m 254.29713,807.35861 c 7.63347,8.13855 7.63347,8.13855 7.63347,8.13855" + id="path5649-2-8-31" + inkscape:connector-curvature="0" /> + <path + style="fill:none;stroke:#ffffff;stroke-width:5;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" + d="m 254.18314,807.10607 c -7.63347,8.13855 -7.63347,8.13855 -7.63347,8.13855" + id="path5649-2-8-1-52" + inkscape:connector-curvature="0" /> + </g> + <g + id="g5834-6-6" + transform="translate(-28.378807,-0.1262667)"> + <path + style="fill:none;stroke:#ffffff;stroke-width:5;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" + d="m 254.29713,807.35861 c 7.63347,8.13855 7.63347,8.13855 7.63347,8.13855" + id="path5649-2-8-3-9" + inkscape:connector-curvature="0" /> + <path + style="fill:none;stroke:#ffffff;stroke-width:5;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" + d="m 254.18314,807.10607 c -7.63347,8.13855 -7.63347,8.13855 -7.63347,8.13855" + id="path5649-2-8-1-8-4" + inkscape:connector-curvature="0" /> + </g> + <path + inkscape:connector-curvature="0" + id="path5647-1-1-5-4" + d="m 275.07468,902.4815 c -10e-6,-95.09507 -10e-6,-95.09507 -10e-6,-95.09507" + style="fill:none;stroke:#ffffff;stroke-width:5;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" /> + <g + transform="translate(20.83129,0.06533)" + id="g5834-5-6"> + <path + style="fill:none;stroke:#ffffff;stroke-width:5;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" + d="m 254.29713,807.35861 c 7.63347,8.13855 7.63347,8.13855 7.63347,8.13855" + id="path5649-2-8-0-0" + inkscape:connector-curvature="0" /> + <path + style="fill:none;stroke:#ffffff;stroke-width:5;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" + d="m 254.18314,807.10607 c -7.63347,8.13855 -7.63347,8.13855 -7.63347,8.13855" + id="path5649-2-8-1-1-7" + inkscape:connector-curvature="0" /> + </g> + <path + inkscape:connector-curvature="0" + id="path5647-1-1-2-4" + d="m 300.24339,877.05907 c -10e-6,-69.73797 -10e-6,-69.73797 -10e-6,-69.73797" + style="fill:none;stroke:#ffffff;stroke-width:5;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" /> + <g + transform="translate(46,2.3999999e-6)" + id="g5834-64-3"> + <path + style="fill:none;stroke:#ffffff;stroke-width:5;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" + d="m 254.29713,807.35861 c 7.63347,8.13855 7.63347,8.13855 7.63347,8.13855" + id="path5649-2-8-8-7" + inkscape:connector-curvature="0" /> + <path + style="fill:none;stroke:#ffffff;stroke-width:5;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" + d="m 254.18314,807.10607 c -7.63347,8.13855 -7.63347,8.13855 -7.63347,8.13855" + id="path5649-2-8-1-5-9" + inkscape:connector-curvature="0" /> + </g> + <path + inkscape:connector-curvature="0" + id="path5647-1-1-6-0" + d="m 326.24339,852.41621 c -10e-6,-45.09511 -10e-6,-45.09511 -10e-6,-45.09511" + style="fill:none;stroke:#ffffff;stroke-width:5;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" /> + <g + transform="translate(72,2.3999999e-6)" + id="g5834-2-0"> + <path + style="fill:none;stroke:#ffffff;stroke-width:5;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" + d="m 254.29713,807.35861 c 7.63347,8.13855 7.63347,8.13855 7.63347,8.13855" + id="path5649-2-8-5-2" + inkscape:connector-curvature="0" /> + <path + style="fill:none;stroke:#ffffff;stroke-width:5;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" + d="m 254.18314,807.10607 c -7.63347,8.13855 -7.63347,8.13855 -7.63347,8.13855" + id="path5649-2-8-1-2-2" + inkscape:connector-curvature="0" /> + </g> + </g> + <g + transform="translate(-68.90787,-423.21518)" + id="g5915-69"> + <path + inkscape:connector-curvature="0" + id="path5647-1-1-0" + d="m 250.24339,924.91621 c -1e-5,-117.59511 -1e-5,-117.59511 -1e-5,-117.59511" + style="fill:none;stroke:#ffffff;stroke-width:5;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" /> + <path + inkscape:connector-curvature="0" + id="path5647-1-1-4-3" + d="m 225.79828,952.17492 c -1e-5,-145.09639 -1e-5,-145.09639 -1e-5,-145.09639" + style="fill:none;stroke:#ffffff;stroke-width:5;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" /> + <g + transform="translate(-4,0)" + id="g5834-55"> + <path + style="fill:none;stroke:#ffffff;stroke-width:5;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" + d="m 254.29713,807.35861 c 7.63347,8.13855 7.63347,8.13855 7.63347,8.13855" + id="path5649-2-8-87" + inkscape:connector-curvature="0" /> + <path + style="fill:none;stroke:#ffffff;stroke-width:5;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" + d="m 254.18314,807.10607 c -7.63347,8.13855 -7.63347,8.13855 -7.63347,8.13855" + id="path5649-2-8-1-17" + inkscape:connector-curvature="0" /> + </g> + <g + id="g5834-6-0" + transform="translate(-28.378807,-0.1262667)"> + <path + style="fill:none;stroke:#ffffff;stroke-width:5;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" + d="m 254.29713,807.35861 c 7.63347,8.13855 7.63347,8.13855 7.63347,8.13855" + id="path5649-2-8-3-6" + inkscape:connector-curvature="0" /> + <path + style="fill:none;stroke:#ffffff;stroke-width:5;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" + d="m 254.18314,807.10607 c -7.63347,8.13855 -7.63347,8.13855 -7.63347,8.13855" + id="path5649-2-8-1-8-0" + inkscape:connector-curvature="0" /> + </g> + <path + inkscape:connector-curvature="0" + id="path5647-1-1-5-41" + d="m 275.07468,902.4815 c -10e-6,-95.09507 -10e-6,-95.09507 -10e-6,-95.09507" + style="fill:none;stroke:#ffffff;stroke-width:5;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" /> + <g + transform="translate(20.83129,0.06533)" + id="g5834-5-3"> + <path + style="fill:none;stroke:#ffffff;stroke-width:5;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" + d="m 254.29713,807.35861 c 7.63347,8.13855 7.63347,8.13855 7.63347,8.13855" + id="path5649-2-8-0-02" + inkscape:connector-curvature="0" /> + <path + style="fill:none;stroke:#ffffff;stroke-width:5;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" + d="m 254.18314,807.10607 c -7.63347,8.13855 -7.63347,8.13855 -7.63347,8.13855" + id="path5649-2-8-1-1-9" + inkscape:connector-curvature="0" /> + </g> + <path + inkscape:connector-curvature="0" + id="path5647-1-1-2-6" + d="m 300.24339,877.05907 c -10e-6,-69.73797 -10e-6,-69.73797 -10e-6,-69.73797" + style="fill:none;stroke:#ffffff;stroke-width:5;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" /> + <g + transform="translate(46,2.3999999e-6)" + id="g5834-64-0"> + <path + style="fill:none;stroke:#ffffff;stroke-width:5;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" + d="m 254.29713,807.35861 c 7.63347,8.13855 7.63347,8.13855 7.63347,8.13855" + id="path5649-2-8-8-9" + inkscape:connector-curvature="0" /> + <path + style="fill:none;stroke:#ffffff;stroke-width:5;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" + d="m 254.18314,807.10607 c -7.63347,8.13855 -7.63347,8.13855 -7.63347,8.13855" + id="path5649-2-8-1-5-3" + inkscape:connector-curvature="0" /> + </g> + <path + inkscape:connector-curvature="0" + id="path5647-1-1-6-5" + d="m 326.24339,852.41621 c -10e-6,-45.09511 -10e-6,-45.09511 -10e-6,-45.09511" + style="fill:none;stroke:#ffffff;stroke-width:5;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" /> + <g + transform="translate(72,2.3999999e-6)" + id="g5834-2-4"> + <path + style="fill:none;stroke:#ffffff;stroke-width:5;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" + d="m 254.29713,807.35861 c 7.63347,8.13855 7.63347,8.13855 7.63347,8.13855" + id="path5649-2-8-5-3" + inkscape:connector-curvature="0" /> + <path + style="fill:none;stroke:#ffffff;stroke-width:5;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" + d="m 254.18314,807.10607 c -7.63347,8.13855 -7.63347,8.13855 -7.63347,8.13855" + id="path5649-2-8-1-2-6" + inkscape:connector-curvature="0" /> + </g> + </g> + <g + id="g5757-4" + transform="matrix(0.96592577,0.25881901,0.25881901,-0.96592577,-270.37522,1148.3182)" + style="stroke-width:10.00000095;stroke-miterlimit:4;stroke-dasharray:none"> + <g + id="g6147" + transform="matrix(0.90919541,0.41636968,-0.41636968,0.90919541,356.68251,-289.80107)"> + <path + sodipodi:nodetypes="cc" + style="opacity:0.90000006;fill:none;stroke:#030000;stroke-width:8.35892296;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" + d="m 844.88702,754.98458 c 98.46431,22.94404 97.08442,22.5743 97.08442,22.5743" + id="path5647-8-3" + inkscape:connector-curvature="0" /> + <path + style="opacity:0.90000006;fill:none;stroke:#030000;stroke-width:10.00000095;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" + d="M 942.20503,775.99548 C 932.40327,762.5147 932.40327,762.5147 932.40327,762.5147" + id="path5649-0-1" + inkscape:connector-curvature="0" /> + <path + style="opacity:0.90000006;fill:none;stroke:#030000;stroke-width:10.00000095;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" + d="m 942.18939,778.15187 c -13.48077,9.80175 -13.48077,9.80175 -13.48077,9.80175" + id="path5649-8-92-9" + inkscape:connector-curvature="0" /> + </g> + </g> + <g + id="g5722-1" + transform="matrix(1,0,0,-1,-382.79865,1227.6835)"> + <path + inkscape:connector-curvature="0" + id="path5647-1-0" + d="m 669.99529,844.65261 c 83.15229,-83.1523 83.15229,-83.1523 83.15229,-83.1523" + style="opacity:0.90000006;fill:none;stroke:#030000;stroke-width:5;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" /> + <path + inkscape:connector-curvature="0" + id="path5649-2-9" + d="m 753.88771,760.96455 c 0,16.66751 0,16.66751 0,16.66751" + style="opacity:0.90000006;fill:none;stroke:#030000;stroke-width:5;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" /> + <path + inkscape:connector-curvature="0" + id="path5649-8-9-4" + d="m 753.78309,760.84726 c -16.6675,0 -16.6675,0 -16.6675,0" + style="opacity:0.90000006;fill:none;stroke:#030000;stroke-width:5;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" /> + </g> + <g + inkscape:label="Layer 1" + id="layer1-74" + transform="matrix(2.985984,0,0,2.985984,799.15302,803.95774)"> + <g + transform="matrix(0.486246,0,0,0.481106,-0.9712,-0.678179)" + id="g1974"> + <path + sodipodi:type="arc" + style="color:#000000;fill:url(#radialGradient2003);fill-opacity:1;fill-rule:evenodd;stroke:none;stroke-width:1;marker:none;visibility:visible;display:inline;overflow:visible" + id="path2452" + sodipodi:cx="24.218407" + sodipodi:cy="35.051105" + sodipodi:rx="16.882174" + sodipodi:ry="4.552" + d="m 41.10058,35.051105 c 0,2.514001 -7.558406,4.552001 -16.882173,4.552001 -9.323767,0 -16.8821739,-2.038 -16.8821739,-4.552001 0,-2.514 7.5584069,-4.552 16.8821739,-4.552 9.323767,0 16.882173,2.038 16.882173,4.552 z" + transform="matrix(1,0,0,1.368932,-1.978553,-13.61713)" /> + <path + sodipodi:type="arc" + style="color:#000000;fill:#adb0aa;fill-opacity:1;fill-rule:evenodd;stroke:#4b4d4a;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dashoffset:0;marker:none;visibility:visible;display:inline;overflow:visible" + id="path2407" + sodipodi:cx="-35.658386" + sodipodi:cy="29.716238" + sodipodi:rx="9.3944187" + sodipodi:ry="3.939595" + d="m -26.263968,29.716238 c 0,2.175778 -4.206024,3.939595 -9.394418,3.939595 -5.188394,0 -9.394419,-1.763817 -9.394419,-3.939595 0,-2.175778 4.206025,-3.939595 9.394419,-3.939595 5.188394,0 9.394418,1.763817 9.394418,3.939595 z" + transform="translate(57.53339,3.203427)" /> + <path + transform="matrix(0.940273,0,0,0.940273,55.40361,4.271194)" + d="m -26.263968,29.716238 c 0,2.175778 -4.206024,3.939595 -9.394418,3.939595 -5.188394,0 -9.394419,-1.763817 -9.394419,-3.939595 0,-2.175778 4.206025,-3.939595 9.394419,-3.939595 5.188394,0 9.394418,1.763817 9.394418,3.939595 z" + sodipodi:ry="3.939595" + sodipodi:rx="9.3944187" + sodipodi:cy="29.716238" + sodipodi:cx="-35.658386" + id="path1825" + style="color:#000000;fill:none;stroke:#7b7f7a;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dashoffset:0;marker:none;visibility:visible;display:inline;overflow:visible" + sodipodi:type="arc" /> + <path + sodipodi:type="arc" + style="color:#000000;fill:none;stroke:url(#linearGradient2005);stroke-width:0.68065339;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dashoffset:0;marker:none;visibility:visible;display:inline;overflow:visible" + id="path2983" + sodipodi:cx="-35.658386" + sodipodi:cy="29.716238" + sodipodi:rx="9.3944187" + sodipodi:ry="3.939595" + d="m -26.263968,29.716238 c 0,2.175778 -4.206024,3.939595 -9.394418,3.939595 -5.188394,0 -9.394419,-1.763817 -9.394419,-3.939595 0,-2.175778 4.206025,-3.939595 9.394419,-3.939595 5.188394,0 9.394418,1.763817 9.394418,3.939595 z" + transform="matrix(0.940273,0,0,0.940273,55.40361,3.521194)" /> + <path + sodipodi:nodetypes="ccccccccccccccccc" + style="fill:#d0d0d0;fill-opacity:1;fill-rule:evenodd;stroke:#979797;stroke-width:0.40000001;stroke-linecap:butt;stroke-linejoin:round;stroke-miterlimit:4;stroke-opacity:1" + d="m 25.6875,28.766243 -0.0625,1 c 0,0 4.324108,3.599166 9,4.202507 2.337946,0.30167 4.753675,0.702412 6.75,1.1875 1.996325,0.485088 3.588356,1.119606 4.125,1.65625 0.310411,0.310411 0.451063,0.573639 0.5,0.78125 0.04894,0.207611 0.03822,0.354815 -0.09375,0.5625 -0.263933,0.41537 -1.079857,0.967652 -2.46875,1.40625 C 40.659715,40.439695 35.717076,41 28.875,41 l 0,1 c 6.895998,0 11.863665,-0.527671 14.84375,-1.46875 1.490042,-0.47054 2.524942,-1.015687 3.03125,-1.8125 C 47.003154,38.320344 47.107321,37.830301 47,37.375 46.892679,36.919699 46.615445,36.490445 46.21875,36.09375 45.34118,35.21618 43.681912,34.68731 41.625,34.1875 39.568088,33.68769 37.109264,33.273171 34.75,32.96875 30.031473,32.359908 25.6875,28.766243 25.6875,28.766243 z" + id="path2411" + inkscape:connector-curvature="0" /> + <path + transform="matrix(1,0,0,1.368932,-1.978553,-19.02126)" + d="m 41.10058,35.051105 c 0,2.514001 -7.558406,4.552001 -16.882173,4.552001 -9.323767,0 -16.8821739,-2.038 -16.8821739,-4.552001 0,-2.514 7.5584069,-4.552 16.8821739,-4.552 9.323767,0 16.882173,2.038 16.882173,4.552 z" + sodipodi:ry="4.552" + sodipodi:rx="16.882174" + sodipodi:cy="35.051105" + sodipodi:cx="24.218407" + id="path2462" + style="color:#000000;fill:url(#radialGradient2007);fill-opacity:1;fill-rule:evenodd;stroke:none;stroke-width:1;marker:none;visibility:visible;display:inline;overflow:visible" + sodipodi:type="arc" /> + <rect + y="30.703611" + x="17.472397" + height="2.7400389" + width="9.0396729" + id="rect2699" + style="color:#000000;fill:url(#linearGradient2009);fill-opacity:1;fill-rule:evenodd;stroke:none;stroke-width:0.60872948;marker:none;visibility:visible;display:inline;overflow:visible" /> + <path + style="color:#000000;fill:url(#linearGradient2011);fill-opacity:1;fill-rule:evenodd;stroke:url(#linearGradient2013);stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dashoffset:0;marker:none;visibility:visible;display:inline;overflow:visible" + d="m 7.0809024,1.6956221 29.5881946,0 c 0.911342,0 1.624147,0.5834818 1.666752,1.401587 l 1.332044,25.5781139 c 0.05821,1.117735 -0.901056,2.020305 -2.020305,2.020305 l -31.545176,0 c -1.1192491,0 -2.078514,-0.90257 -2.0203052,-2.020305 L 5.4141506,3.0972091 c 0.040284,-0.7735346 0.5475027,-1.401587 1.6667518,-1.401587 z" + id="rect2404" + sodipodi:nodetypes="cssssssss" + inkscape:connector-curvature="0" /> + <path + sodipodi:nodetypes="ccccc" + id="path2377" + d="m 8.4105348,4.3058272 -1.242195,22.0453168 27.6503892,0 L 33.483712,4.3992558 8.4105348,4.3058272 z" + style="fill:url(#linearGradient2015);fill-opacity:1;fill-rule:evenodd;stroke:#000079;stroke-width:0.5;stroke-linecap:butt;stroke-linejoin:round;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" + inkscape:connector-curvature="0" /> + <path + style="fill:none;stroke:url(#linearGradient2017);stroke-width:0.99618119;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:0.24840764" + d="m 6.1774331,28.735789 31.4284769,0" + id="path2393" + inkscape:connector-curvature="0" /> + <path + sodipodi:nodetypes="cssssssss" + id="path2397" + d="M 6.9145985,2.7063396 36.760101,2.6685383 c 0.283697,-3.593e-4 0.559302,0.2372498 0.582105,0.6525438 L 38.704098,28.12433 c 0.05804,1.057031 -0.539749,1.785871 -1.598371,1.785871 l -30.5239687,0 c -1.0586228,0 -1.5930144,-0.728791 -1.5358714,-1.785871 L 6.3699773,3.6301633 C 6.4086732,2.9143326 6.5363627,2.7068187 6.9145985,2.7063396 z" + style="color:#000000;fill:none;stroke:url(#linearGradient2019);stroke-width:0.99999964;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:0.70063692;stroke-dashoffset:0;marker:none;visibility:visible;display:inline;overflow:visible" + inkscape:connector-curvature="0" /> + <path + sodipodi:nodetypes="ccccc" + style="opacity:0.53142856;fill:url(#linearGradient2021);fill-opacity:1;fill-rule:evenodd;stroke:none" + d="M 8.7115364,4.7463626 7.9090069,22.616693 C 18.953645,20.216063 19.33047,12.124494 33.063039,9.4699426 L 32.901567,4.8124267 8.7115364,4.7463626 z" + id="path2443" + inkscape:connector-curvature="0" /> + <path + transform="matrix(1.264398,0,0,1.291262,-6.216332,-4.000423)" + d="m 41.10058,35.051105 c 0,2.514001 -7.558406,4.552001 -16.882173,4.552001 -9.323767,0 -16.8821739,-2.038 -16.8821739,-4.552001 0,-2.514 7.5584069,-4.552 16.8821739,-4.552 9.323767,0 16.882173,2.038 16.882173,4.552 z" + sodipodi:ry="4.552" + sodipodi:rx="16.882174" + sodipodi:cy="35.051105" + sodipodi:cx="24.218407" + id="path2657" + style="color:#000000;fill:url(#radialGradient2023);fill-opacity:1;fill-rule:evenodd;stroke:none;stroke-width:1;marker:none;visibility:visible;display:inline;overflow:visible" + sodipodi:type="arc" /> + <path + sodipodi:nodetypes="cssssssss" + id="path2409" + d="m 6.4621839,36.817452 31.0024061,0 c 1.119249,0 0.977355,0.271438 1.092227,0.612846 l 2.834646,8.42481 c 0.114872,0.341409 0.02702,0.612846 -1.092227,0.612846 l -36.6716978,0 c -1.1192491,0 -1.2070995,-0.271437 -1.0922275,-0.612846 l 2.8346457,-8.42481 c 0.114872,-0.341409 -0.027022,-0.612846 1.0922275,-0.612846 z" + style="color:#000000;fill:url(#linearGradient2025);fill-opacity:1;fill-rule:evenodd;stroke:url(#linearGradient2027);stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0;marker:none;visibility:visible;display:inline;overflow:visible" + inkscape:connector-curvature="0" /> + <path + sodipodi:nodetypes="ccccccccc" + id="path2611" + d="m 6.3916892,38.829113 -1.7677669,5.126525 5.4800777,0 0.53033,-2.032932 14.849242,0 0.549679,2.075114 6.167835,0 -1.679378,-5.168707 -24.1300188,0 z" + style="fill:#7a7d77;fill-opacity:1;fill-rule:evenodd;stroke:none" + inkscape:connector-curvature="0" /> + <path + id="path2613" + d="m 11.076272,42.27626 -0.441942,1.679379 14.760854,0 -0.441942,-1.767767 -13.87697,0.08839 z" + style="fill:#777874;fill-opacity:1;fill-rule:evenodd;stroke:none" + inkscape:connector-curvature="0" /> + <path + style="color:#000000;fill:#777a75;fill-opacity:1;fill-rule:evenodd;stroke:none;stroke-width:0.25pt;marker:none;visibility:visible;display:inline;overflow:visible" + d="m 37.592776,38.829114 1.679379,5.038136 -5.480078,-0.08839 -1.502602,-4.861359 5.303301,-0.08839 z" + id="path2619" + inkscape:connector-curvature="0" /> + <path + id="path2615" + d="m 37.592776,38.298786 1.679379,5.038136 -5.480078,-0.08839 -1.502602,-4.861359 5.303301,-0.08839 z" + style="color:#000000;fill:url(#linearGradient2029);fill-opacity:1;fill-rule:evenodd;stroke:none;stroke-width:0.25pt;marker:none;visibility:visible;display:inline;overflow:visible" + inkscape:connector-curvature="0" /> + <path + style="fill:url(#linearGradient2031);fill-opacity:1;fill-rule:evenodd;stroke:none" + d="m 6.3916892,38.210397 -1.7677669,5.126525 5.4800777,0 0.53033,-2.032932 14.849242,0 0.549679,2.075114 6.167835,0 -1.679378,-5.168707 -24.1300188,0 z" + id="path2617" + sodipodi:nodetypes="ccccccccc" + inkscape:connector-curvature="0" /> + <path + style="color:#000000;fill:url(#linearGradient2033);fill-opacity:1;fill-rule:evenodd;stroke:none;stroke-width:0.25pt;marker:none;visibility:visible;display:inline;overflow:visible" + d="m 11.076272,41.745932 -0.441942,1.679379 14.760854,0 -0.441942,-1.767767 -13.87697,0.08839 z" + id="path2621" + inkscape:connector-curvature="0" /> + <path + style="color:#000000;fill:none;stroke:url(#linearGradient2035);stroke-width:0.5;stroke-linecap:butt;stroke-linejoin:round;stroke-miterlimit:4;stroke-opacity:1;stroke-dashoffset:0;marker:none;visibility:visible;display:inline;overflow:visible" + d="m 6.1278189,37.578116 31.8258151,0 2.637179,8.092563 -37.2610701,0 2.798076,-8.092563 z" + id="path2631" + sodipodi:nodetypes="ccccc" + inkscape:connector-curvature="0" /> + <path + transform="matrix(1.331237,0,0,0.658449,-10.41933,2.853866)" + d="m 35.620504,3.9384086 c 0,0.4637476 -0.375941,0.8396893 -0.839689,0.8396893 -0.463747,0 -0.839689,-0.3759417 -0.839689,-0.8396893 0,-0.4637476 0.375942,-0.8396893 0.839689,-0.8396893 0.463748,0 0.839689,0.3759417 0.839689,0.8396893 z" + sodipodi:ry="0.83968931" + sodipodi:rx="0.83968931" + sodipodi:cy="3.9384086" + sodipodi:cx="34.780815" + id="path2709" + style="color:#000000;fill:url(#linearGradient2037);fill-opacity:1;fill-rule:evenodd;stroke:none;stroke-width:0.5;marker:none;visibility:visible;display:inline;overflow:visible" + sodipodi:type="arc" /> + <path + sodipodi:type="arc" + style="color:#000000;fill:url(#linearGradient2039);fill-opacity:1;fill-rule:evenodd;stroke:none;stroke-width:0.5;marker:none;visibility:visible;display:inline;overflow:visible" + id="path2719" + sodipodi:cx="34.780815" + sodipodi:cy="3.9384086" + sodipodi:rx="0.83968931" + sodipodi:ry="0.83968931" + d="m 35.620504,3.9384086 c 0,0.4637476 -0.375941,0.8396893 -0.839689,0.8396893 -0.463747,0 -0.839689,-0.3759417 -0.839689,-0.8396893 0,-0.4637476 0.375942,-0.8396893 0.839689,-0.8396893 0.463748,0 0.839689,0.3759417 0.839689,0.8396893 z" + transform="matrix(1.331237,0,0,0.658449,-10.30573,4.959651)" /> + <path + transform="matrix(1.331237,0,0,0.658449,-10.19213,6.959651)" + d="m 35.620504,3.9384086 c 0,0.4637476 -0.375941,0.8396893 -0.839689,0.8396893 -0.463747,0 -0.839689,-0.3759417 -0.839689,-0.8396893 0,-0.4637476 0.375942,-0.8396893 0.839689,-0.8396893 0.463748,0 0.839689,0.3759417 0.839689,0.8396893 z" + sodipodi:ry="0.83968931" + sodipodi:rx="0.83968931" + sodipodi:cy="3.9384086" + sodipodi:cx="34.780815" + id="path2723" + style="color:#000000;fill:url(#linearGradient2041);fill-opacity:1;fill-rule:evenodd;stroke:none;stroke-width:0.5;marker:none;visibility:visible;display:inline;overflow:visible" + sodipodi:type="arc" /> + <path + sodipodi:type="arc" + style="color:#000000;fill:url(#linearGradient2043);fill-opacity:1;fill-rule:evenodd;stroke:none;stroke-width:0.5;marker:none;visibility:visible;display:inline;overflow:visible" + id="path2727" + sodipodi:cx="34.780815" + sodipodi:cy="3.9384086" + sodipodi:rx="0.83968931" + sodipodi:ry="0.83968931" + d="m 35.620504,3.9384086 c 0,0.4637476 -0.375941,0.8396893 -0.839689,0.8396893 -0.463747,0 -0.839689,-0.3759417 -0.839689,-0.8396893 0,-0.4637476 0.375942,-0.8396893 0.839689,-0.8396893 0.463748,0 0.839689,0.3759417 0.839689,0.8396893 z" + transform="matrix(1.331237,0,0,0.658449,-10.07853,8.959651)" /> + <path + transform="matrix(1.331237,0,0,0.658449,-9.96493,10.95965)" + d="m 35.620504,3.9384086 c 0,0.4637476 -0.375941,0.8396893 -0.839689,0.8396893 -0.463747,0 -0.839689,-0.3759417 -0.839689,-0.8396893 0,-0.4637476 0.375942,-0.8396893 0.839689,-0.8396893 0.463748,0 0.839689,0.3759417 0.839689,0.8396893 z" + sodipodi:ry="0.83968931" + sodipodi:rx="0.83968931" + sodipodi:cy="3.9384086" + sodipodi:cx="34.780815" + id="path2731" + style="color:#000000;fill:url(#linearGradient2045);fill-opacity:1;fill-rule:evenodd;stroke:none;stroke-width:0.5;marker:none;visibility:visible;display:inline;overflow:visible" + sodipodi:type="arc" /> + <path + id="text2735" + d="m 20,27.317666 0.281716,0 c 0.08376,1e-6 0.147985,0.01866 0.19266,0.05599 0.04497,0.03703 0.06745,0.08994 0.06745,0.158714 -1e-6,0.06907 -0.02248,0.122268 -0.06745,0.159595 -0.04467,0.03703 -0.108895,0.05555 -0.19266,0.05555 l -0.111981,0 0,0.22837 -0.169735,0 0,-0.658219 m 0.169735,0.123003 0,0.183843 0.0939,0 c 0.03292,0 0.05834,-0.0079 0.07627,-0.02381 0.01793,-0.01617 0.02689,-0.03894 0.02689,-0.06834 0,-0.02939 -0.009,-0.05202 -0.02689,-0.06789 -0.01793,-0.01587 -0.04335,-0.02381 -0.07627,-0.02381 l -0.0939,0 m 0.792244,-0.0119 c -0.05173,1e-6 -0.09185,0.01911 -0.120358,0.05731 -0.02851,0.03821 -0.04276,0.092 -0.04276,0.161359 0,0.06907 0.01425,0.122709 0.04276,0.160918 0.02851,0.03821 0.06863,0.05731 0.120358,0.05731 0.05202,0 0.09229,-0.0191 0.120799,-0.05731 0.02851,-0.03821 0.04276,-0.09185 0.04276,-0.160918 -10e-7,-0.06936 -0.01425,-0.123149 -0.04276,-0.161359 -0.02851,-0.03821 -0.06878,-0.05731 -0.120799,-0.05731 m 0,-0.123003 c 0.105808,1e-6 0.188692,0.03027 0.248651,0.09082 0.05996,0.06055 0.08994,0.144165 0.08994,0.250855 -1e-6,0.106397 -0.02998,0.189868 -0.08994,0.250414 -0.05996,0.06055 -0.142843,0.09082 -0.248651,0.09082 -0.105515,0 -0.188399,-0.03027 -0.248651,-0.09082 -0.05996,-0.06055 -0.08994,-0.144017 -0.08994,-0.250414 0,-0.10669 0.02998,-0.190309 0.08994,-0.250855 0.06025,-0.06055 0.143136,-0.09082 0.248651,-0.09082 m 0.466441,0.0119 0.189574,0 0.239393,0.451451 0,-0.451451 0.160918,0 0,0.658219 -0.189575,0 -0.239392,-0.451451 0,0.451451 -0.160918,0 0,-0.658219 m 0.663069,0 0.185606,0 0.149896,0.234543 0.149896,-0.234543 0.186048,0 -0.250856,0.380912 0,0.277307 -0.169735,0 0,-0.277307 -0.250855,-0.380912" + style="font-size:0.9029026px;font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;writing-mode:lr-tb;text-anchor:start;fill:#4a4a4a;fill-opacity:1;stroke:none;font-family:Bitstream Vera Sans" + inkscape:connector-curvature="0" /> + </g> + </g> + <g + inkscape:label="Layer 1" + id="layer1-74-4" + transform="matrix(2.985984,0,0,2.985984,880.29588,818.24344)"> + <g + transform="matrix(0.486246,0,0,0.481106,-0.9712,-0.678179)" + id="g1974-1"> + <path + sodipodi:type="arc" + style="color:#000000;fill:url(#radialGradient2003-1);fill-opacity:1;fill-rule:evenodd;stroke:none;stroke-width:1;marker:none;visibility:visible;display:inline;overflow:visible" + id="path2452-6" + sodipodi:cx="24.218407" + sodipodi:cy="35.051105" + sodipodi:rx="16.882174" + sodipodi:ry="4.552" + d="m 41.10058,35.051105 c 0,2.514001 -7.558406,4.552001 -16.882173,4.552001 -9.323767,0 -16.8821739,-2.038 -16.8821739,-4.552001 0,-2.514 7.5584069,-4.552 16.8821739,-4.552 9.323767,0 16.882173,2.038 16.882173,4.552 z" + transform="matrix(1,0,0,1.368932,-1.978553,-13.61713)" /> + <path + sodipodi:type="arc" + style="color:#000000;fill:#adb0aa;fill-opacity:1;fill-rule:evenodd;stroke:#4b4d4a;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dashoffset:0;marker:none;visibility:visible;display:inline;overflow:visible" + id="path2407-4" + sodipodi:cx="-35.658386" + sodipodi:cy="29.716238" + sodipodi:rx="9.3944187" + sodipodi:ry="3.939595" + d="m -26.263968,29.716238 c 0,2.175778 -4.206024,3.939595 -9.394418,3.939595 -5.188394,0 -9.394419,-1.763817 -9.394419,-3.939595 0,-2.175778 4.206025,-3.939595 9.394419,-3.939595 5.188394,0 9.394418,1.763817 9.394418,3.939595 z" + transform="translate(57.53339,3.203427)" /> + <path + transform="matrix(0.940273,0,0,0.940273,55.40361,4.271194)" + d="m -26.263968,29.716238 c 0,2.175778 -4.206024,3.939595 -9.394418,3.939595 -5.188394,0 -9.394419,-1.763817 -9.394419,-3.939595 0,-2.175778 4.206025,-3.939595 9.394419,-3.939595 5.188394,0 9.394418,1.763817 9.394418,3.939595 z" + sodipodi:ry="3.939595" + sodipodi:rx="9.3944187" + sodipodi:cy="29.716238" + sodipodi:cx="-35.658386" + id="path1825-3" + style="color:#000000;fill:none;stroke:#7b7f7a;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dashoffset:0;marker:none;visibility:visible;display:inline;overflow:visible" + sodipodi:type="arc" /> + <path + sodipodi:type="arc" + style="color:#000000;fill:none;stroke:url(#linearGradient2005-3);stroke-width:0.68065339;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dashoffset:0;marker:none;visibility:visible;display:inline;overflow:visible" + id="path2983-5" + sodipodi:cx="-35.658386" + sodipodi:cy="29.716238" + sodipodi:rx="9.3944187" + sodipodi:ry="3.939595" + d="m -26.263968,29.716238 c 0,2.175778 -4.206024,3.939595 -9.394418,3.939595 -5.188394,0 -9.394419,-1.763817 -9.394419,-3.939595 0,-2.175778 4.206025,-3.939595 9.394419,-3.939595 5.188394,0 9.394418,1.763817 9.394418,3.939595 z" + transform="matrix(0.940273,0,0,0.940273,55.40361,3.521194)" /> + <path + sodipodi:nodetypes="ccccccccccccccccc" + style="fill:#d0d0d0;fill-opacity:1;fill-rule:evenodd;stroke:#979797;stroke-width:0.40000001;stroke-linecap:butt;stroke-linejoin:round;stroke-miterlimit:4;stroke-opacity:1" + d="m 25.6875,28.766243 -0.0625,1 c 0,0 4.324108,3.599166 9,4.202507 2.337946,0.30167 4.753675,0.702412 6.75,1.1875 1.996325,0.485088 3.588356,1.119606 4.125,1.65625 0.310411,0.310411 0.451063,0.573639 0.5,0.78125 0.04894,0.207611 0.03822,0.354815 -0.09375,0.5625 -0.263933,0.41537 -1.079857,0.967652 -2.46875,1.40625 C 40.659715,40.439695 35.717076,41 28.875,41 l 0,1 c 6.895998,0 11.863665,-0.527671 14.84375,-1.46875 1.490042,-0.47054 2.524942,-1.015687 3.03125,-1.8125 C 47.003154,38.320344 47.107321,37.830301 47,37.375 46.892679,36.919699 46.615445,36.490445 46.21875,36.09375 45.34118,35.21618 43.681912,34.68731 41.625,34.1875 39.568088,33.68769 37.109264,33.273171 34.75,32.96875 30.031473,32.359908 25.6875,28.766243 25.6875,28.766243 z" + id="path2411-4" + inkscape:connector-curvature="0" /> + <path + transform="matrix(1,0,0,1.368932,-1.978553,-19.02126)" + d="m 41.10058,35.051105 c 0,2.514001 -7.558406,4.552001 -16.882173,4.552001 -9.323767,0 -16.8821739,-2.038 -16.8821739,-4.552001 0,-2.514 7.5584069,-4.552 16.8821739,-4.552 9.323767,0 16.882173,2.038 16.882173,4.552 z" + sodipodi:ry="4.552" + sodipodi:rx="16.882174" + sodipodi:cy="35.051105" + sodipodi:cx="24.218407" + id="path2462-8" + style="color:#000000;fill:url(#radialGradient2007-9);fill-opacity:1;fill-rule:evenodd;stroke:none;stroke-width:1;marker:none;visibility:visible;display:inline;overflow:visible" + sodipodi:type="arc" /> + <rect + y="30.703611" + x="17.472397" + height="2.7400389" + width="9.0396729" + id="rect2699-7" + style="color:#000000;fill:url(#linearGradient2009-3);fill-opacity:1;fill-rule:evenodd;stroke:none;stroke-width:0.60872948;marker:none;visibility:visible;display:inline;overflow:visible" /> + <path + style="color:#000000;fill:url(#linearGradient2011-7);fill-opacity:1;fill-rule:evenodd;stroke:url(#linearGradient2013-8);stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dashoffset:0;marker:none;visibility:visible;display:inline;overflow:visible" + d="m 7.0809024,1.6956221 29.5881946,0 c 0.911342,0 1.624147,0.5834818 1.666752,1.401587 l 1.332044,25.5781139 c 0.05821,1.117735 -0.901056,2.020305 -2.020305,2.020305 l -31.545176,0 c -1.1192491,0 -2.078514,-0.90257 -2.0203052,-2.020305 L 5.4141506,3.0972091 c 0.040284,-0.7735346 0.5475027,-1.401587 1.6667518,-1.401587 z" + id="rect2404-3" + sodipodi:nodetypes="cssssssss" + inkscape:connector-curvature="0" /> + <path + sodipodi:nodetypes="ccccc" + id="path2377-3" + d="m 8.4105348,4.3058272 -1.242195,22.0453168 27.6503892,0 L 33.483712,4.3992558 8.4105348,4.3058272 z" + style="fill:url(#linearGradient2015-8);fill-opacity:1;fill-rule:evenodd;stroke:#000079;stroke-width:0.5;stroke-linecap:butt;stroke-linejoin:round;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" + inkscape:connector-curvature="0" /> + <path + style="fill:none;stroke:url(#linearGradient2017-3);stroke-width:0.99618119;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:0.24840764" + d="m 6.1774331,28.735789 31.4284769,0" + id="path2393-5" + inkscape:connector-curvature="0" /> + <path + sodipodi:nodetypes="cssssssss" + id="path2397-0" + d="M 6.9145985,2.7063396 36.760101,2.6685383 c 0.283697,-3.593e-4 0.559302,0.2372498 0.582105,0.6525438 L 38.704098,28.12433 c 0.05804,1.057031 -0.539749,1.785871 -1.598371,1.785871 l -30.5239687,0 c -1.0586228,0 -1.5930144,-0.728791 -1.5358714,-1.785871 L 6.3699773,3.6301633 C 6.4086732,2.9143326 6.5363627,2.7068187 6.9145985,2.7063396 z" + style="color:#000000;fill:none;stroke:url(#linearGradient2019-5);stroke-width:0.99999964;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:0.70063692;stroke-dashoffset:0;marker:none;visibility:visible;display:inline;overflow:visible" + inkscape:connector-curvature="0" /> + <path + sodipodi:nodetypes="ccccc" + style="opacity:0.53142856;fill:url(#linearGradient2021-8);fill-opacity:1;fill-rule:evenodd;stroke:none" + d="M 8.7115364,4.7463626 7.9090069,22.616693 C 18.953645,20.216063 19.33047,12.124494 33.063039,9.4699426 L 32.901567,4.8124267 8.7115364,4.7463626 z" + id="path2443-1" + inkscape:connector-curvature="0" /> + <path + transform="matrix(1.264398,0,0,1.291262,-6.216332,-4.000423)" + d="m 41.10058,35.051105 c 0,2.514001 -7.558406,4.552001 -16.882173,4.552001 -9.323767,0 -16.8821739,-2.038 -16.8821739,-4.552001 0,-2.514 7.5584069,-4.552 16.8821739,-4.552 9.323767,0 16.882173,2.038 16.882173,4.552 z" + sodipodi:ry="4.552" + sodipodi:rx="16.882174" + sodipodi:cy="35.051105" + sodipodi:cx="24.218407" + id="path2657-4" + style="color:#000000;fill:url(#radialGradient2023-3);fill-opacity:1;fill-rule:evenodd;stroke:none;stroke-width:1;marker:none;visibility:visible;display:inline;overflow:visible" + sodipodi:type="arc" /> + <path + sodipodi:nodetypes="cssssssss" + id="path2409-5" + d="m 6.4621839,36.817452 31.0024061,0 c 1.119249,0 0.977355,0.271438 1.092227,0.612846 l 2.834646,8.42481 c 0.114872,0.341409 0.02702,0.612846 -1.092227,0.612846 l -36.6716978,0 c -1.1192491,0 -1.2070995,-0.271437 -1.0922275,-0.612846 l 2.8346457,-8.42481 c 0.114872,-0.341409 -0.027022,-0.612846 1.0922275,-0.612846 z" + style="color:#000000;fill:url(#linearGradient2025-6);fill-opacity:1;fill-rule:evenodd;stroke:url(#linearGradient2027-7);stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0;marker:none;visibility:visible;display:inline;overflow:visible" + inkscape:connector-curvature="0" /> + <path + sodipodi:nodetypes="ccccccccc" + id="path2611-7" + d="m 6.3916892,38.829113 -1.7677669,5.126525 5.4800777,0 0.53033,-2.032932 14.849242,0 0.549679,2.075114 6.167835,0 -1.679378,-5.168707 -24.1300188,0 z" + style="fill:#7a7d77;fill-opacity:1;fill-rule:evenodd;stroke:none" + inkscape:connector-curvature="0" /> + <path + id="path2613-0" + d="m 11.076272,42.27626 -0.441942,1.679379 14.760854,0 -0.441942,-1.767767 -13.87697,0.08839 z" + style="fill:#777874;fill-opacity:1;fill-rule:evenodd;stroke:none" + inkscape:connector-curvature="0" /> + <path + style="color:#000000;fill:#777a75;fill-opacity:1;fill-rule:evenodd;stroke:none;stroke-width:0.25pt;marker:none;visibility:visible;display:inline;overflow:visible" + d="m 37.592776,38.829114 1.679379,5.038136 -5.480078,-0.08839 -1.502602,-4.861359 5.303301,-0.08839 z" + id="path2619-7" + inkscape:connector-curvature="0" /> + <path + id="path2615-8" + d="m 37.592776,38.298786 1.679379,5.038136 -5.480078,-0.08839 -1.502602,-4.861359 5.303301,-0.08839 z" + style="color:#000000;fill:url(#linearGradient2029-8);fill-opacity:1;fill-rule:evenodd;stroke:none;stroke-width:0.25pt;marker:none;visibility:visible;display:inline;overflow:visible" + inkscape:connector-curvature="0" /> + <path + style="fill:url(#linearGradient2031-6);fill-opacity:1;fill-rule:evenodd;stroke:none" + d="m 6.3916892,38.210397 -1.7677669,5.126525 5.4800777,0 0.53033,-2.032932 14.849242,0 0.549679,2.075114 6.167835,0 -1.679378,-5.168707 -24.1300188,0 z" + id="path2617-9" + sodipodi:nodetypes="ccccccccc" + inkscape:connector-curvature="0" /> + <path + style="color:#000000;fill:url(#linearGradient2033-2);fill-opacity:1;fill-rule:evenodd;stroke:none;stroke-width:0.25pt;marker:none;visibility:visible;display:inline;overflow:visible" + d="m 11.076272,41.745932 -0.441942,1.679379 14.760854,0 -0.441942,-1.767767 -13.87697,0.08839 z" + id="path2621-9" + inkscape:connector-curvature="0" /> + <path + style="color:#000000;fill:none;stroke:url(#linearGradient2035-9);stroke-width:0.5;stroke-linecap:butt;stroke-linejoin:round;stroke-miterlimit:4;stroke-opacity:1;stroke-dashoffset:0;marker:none;visibility:visible;display:inline;overflow:visible" + d="m 6.1278189,37.578116 31.8258151,0 2.637179,8.092563 -37.2610701,0 2.798076,-8.092563 z" + id="path2631-3" + sodipodi:nodetypes="ccccc" + inkscape:connector-curvature="0" /> + <path + transform="matrix(1.331237,0,0,0.658449,-10.41933,2.853866)" + d="m 35.620504,3.9384086 c 0,0.4637476 -0.375941,0.8396893 -0.839689,0.8396893 -0.463747,0 -0.839689,-0.3759417 -0.839689,-0.8396893 0,-0.4637476 0.375942,-0.8396893 0.839689,-0.8396893 0.463748,0 0.839689,0.3759417 0.839689,0.8396893 z" + sodipodi:ry="0.83968931" + sodipodi:rx="0.83968931" + sodipodi:cy="3.9384086" + sodipodi:cx="34.780815" + id="path2709-9" + style="color:#000000;fill:url(#linearGradient2037-7);fill-opacity:1;fill-rule:evenodd;stroke:none;stroke-width:0.5;marker:none;visibility:visible;display:inline;overflow:visible" + sodipodi:type="arc" /> + <path + sodipodi:type="arc" + style="color:#000000;fill:url(#linearGradient2039-1);fill-opacity:1;fill-rule:evenodd;stroke:none;stroke-width:0.5;marker:none;visibility:visible;display:inline;overflow:visible" + id="path2719-4" + sodipodi:cx="34.780815" + sodipodi:cy="3.9384086" + sodipodi:rx="0.83968931" + sodipodi:ry="0.83968931" + d="m 35.620504,3.9384086 c 0,0.4637476 -0.375941,0.8396893 -0.839689,0.8396893 -0.463747,0 -0.839689,-0.3759417 -0.839689,-0.8396893 0,-0.4637476 0.375942,-0.8396893 0.839689,-0.8396893 0.463748,0 0.839689,0.3759417 0.839689,0.8396893 z" + transform="matrix(1.331237,0,0,0.658449,-10.30573,4.959651)" /> + <path + transform="matrix(1.331237,0,0,0.658449,-10.19213,6.959651)" + d="m 35.620504,3.9384086 c 0,0.4637476 -0.375941,0.8396893 -0.839689,0.8396893 -0.463747,0 -0.839689,-0.3759417 -0.839689,-0.8396893 0,-0.4637476 0.375942,-0.8396893 0.839689,-0.8396893 0.463748,0 0.839689,0.3759417 0.839689,0.8396893 z" + sodipodi:ry="0.83968931" + sodipodi:rx="0.83968931" + sodipodi:cy="3.9384086" + sodipodi:cx="34.780815" + id="path2723-6" + style="color:#000000;fill:url(#linearGradient2041-7);fill-opacity:1;fill-rule:evenodd;stroke:none;stroke-width:0.5;marker:none;visibility:visible;display:inline;overflow:visible" + sodipodi:type="arc" /> + <path + sodipodi:type="arc" + style="color:#000000;fill:url(#linearGradient2043-8);fill-opacity:1;fill-rule:evenodd;stroke:none;stroke-width:0.5;marker:none;visibility:visible;display:inline;overflow:visible" + id="path2727-4" + sodipodi:cx="34.780815" + sodipodi:cy="3.9384086" + sodipodi:rx="0.83968931" + sodipodi:ry="0.83968931" + d="m 35.620504,3.9384086 c 0,0.4637476 -0.375941,0.8396893 -0.839689,0.8396893 -0.463747,0 -0.839689,-0.3759417 -0.839689,-0.8396893 0,-0.4637476 0.375942,-0.8396893 0.839689,-0.8396893 0.463748,0 0.839689,0.3759417 0.839689,0.8396893 z" + transform="matrix(1.331237,0,0,0.658449,-10.07853,8.959651)" /> + <path + transform="matrix(1.331237,0,0,0.658449,-9.96493,10.95965)" + d="m 35.620504,3.9384086 c 0,0.4637476 -0.375941,0.8396893 -0.839689,0.8396893 -0.463747,0 -0.839689,-0.3759417 -0.839689,-0.8396893 0,-0.4637476 0.375942,-0.8396893 0.839689,-0.8396893 0.463748,0 0.839689,0.3759417 0.839689,0.8396893 z" + sodipodi:ry="0.83968931" + sodipodi:rx="0.83968931" + sodipodi:cy="3.9384086" + sodipodi:cx="34.780815" + id="path2731-5" + style="color:#000000;fill:url(#linearGradient2045-9);fill-opacity:1;fill-rule:evenodd;stroke:none;stroke-width:0.5;marker:none;visibility:visible;display:inline;overflow:visible" + sodipodi:type="arc" /> + <path + id="text2735-5" + d="m 20,27.317666 0.281716,0 c 0.08376,1e-6 0.147985,0.01866 0.19266,0.05599 0.04497,0.03703 0.06745,0.08994 0.06745,0.158714 -1e-6,0.06907 -0.02248,0.122268 -0.06745,0.159595 -0.04467,0.03703 -0.108895,0.05555 -0.19266,0.05555 l -0.111981,0 0,0.22837 -0.169735,0 0,-0.658219 m 0.169735,0.123003 0,0.183843 0.0939,0 c 0.03292,0 0.05834,-0.0079 0.07627,-0.02381 0.01793,-0.01617 0.02689,-0.03894 0.02689,-0.06834 0,-0.02939 -0.009,-0.05202 -0.02689,-0.06789 -0.01793,-0.01587 -0.04335,-0.02381 -0.07627,-0.02381 l -0.0939,0 m 0.792244,-0.0119 c -0.05173,1e-6 -0.09185,0.01911 -0.120358,0.05731 -0.02851,0.03821 -0.04276,0.092 -0.04276,0.161359 0,0.06907 0.01425,0.122709 0.04276,0.160918 0.02851,0.03821 0.06863,0.05731 0.120358,0.05731 0.05202,0 0.09229,-0.0191 0.120799,-0.05731 0.02851,-0.03821 0.04276,-0.09185 0.04276,-0.160918 -10e-7,-0.06936 -0.01425,-0.123149 -0.04276,-0.161359 -0.02851,-0.03821 -0.06878,-0.05731 -0.120799,-0.05731 m 0,-0.123003 c 0.105808,1e-6 0.188692,0.03027 0.248651,0.09082 0.05996,0.06055 0.08994,0.144165 0.08994,0.250855 -1e-6,0.106397 -0.02998,0.189868 -0.08994,0.250414 -0.05996,0.06055 -0.142843,0.09082 -0.248651,0.09082 -0.105515,0 -0.188399,-0.03027 -0.248651,-0.09082 -0.05996,-0.06055 -0.08994,-0.144017 -0.08994,-0.250414 0,-0.10669 0.02998,-0.190309 0.08994,-0.250855 0.06025,-0.06055 0.143136,-0.09082 0.248651,-0.09082 m 0.466441,0.0119 0.189574,0 0.239393,0.451451 0,-0.451451 0.160918,0 0,0.658219 -0.189575,0 -0.239392,-0.451451 0,0.451451 -0.160918,0 0,-0.658219 m 0.663069,0 0.185606,0 0.149896,0.234543 0.149896,-0.234543 0.186048,0 -0.250856,0.380912 0,0.277307 -0.169735,0 0,-0.277307 -0.250855,-0.380912" + style="font-size:0.9029026px;font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;writing-mode:lr-tb;text-anchor:start;fill:#4a4a4a;fill-opacity:1;stroke:none;font-family:Bitstream Vera Sans" + inkscape:connector-curvature="0" /> + </g> + </g> + <g + inkscape:label="Layer 1" + id="layer1-74-4-5" + transform="matrix(2.985984,0,0,2.985984,968.01017,810.24344)"> + <g + transform="matrix(0.486246,0,0,0.481106,-0.9712,-0.678179)" + id="g1974-1-1"> + <path + sodipodi:type="arc" + style="color:#000000;fill:url(#radialGradient2003-1-5);fill-opacity:1;fill-rule:evenodd;stroke:none;stroke-width:1;marker:none;visibility:visible;display:inline;overflow:visible" + id="path2452-6-6" + sodipodi:cx="24.218407" + sodipodi:cy="35.051105" + sodipodi:rx="16.882174" + sodipodi:ry="4.552" + d="m 41.10058,35.051105 c 0,2.514001 -7.558406,4.552001 -16.882173,4.552001 -9.323767,0 -16.8821739,-2.038 -16.8821739,-4.552001 0,-2.514 7.5584069,-4.552 16.8821739,-4.552 9.323767,0 16.882173,2.038 16.882173,4.552 z" + transform="matrix(1,0,0,1.368932,-1.978553,-13.61713)" /> + <path + sodipodi:type="arc" + style="color:#000000;fill:#adb0aa;fill-opacity:1;fill-rule:evenodd;stroke:#4b4d4a;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dashoffset:0;marker:none;visibility:visible;display:inline;overflow:visible" + id="path2407-4-1" + sodipodi:cx="-35.658386" + sodipodi:cy="29.716238" + sodipodi:rx="9.3944187" + sodipodi:ry="3.939595" + d="m -26.263968,29.716238 c 0,2.175778 -4.206024,3.939595 -9.394418,3.939595 -5.188394,0 -9.394419,-1.763817 -9.394419,-3.939595 0,-2.175778 4.206025,-3.939595 9.394419,-3.939595 5.188394,0 9.394418,1.763817 9.394418,3.939595 z" + transform="translate(57.53339,3.203427)" /> + <path + transform="matrix(0.940273,0,0,0.940273,55.40361,4.271194)" + d="m -26.263968,29.716238 c 0,2.175778 -4.206024,3.939595 -9.394418,3.939595 -5.188394,0 -9.394419,-1.763817 -9.394419,-3.939595 0,-2.175778 4.206025,-3.939595 9.394419,-3.939595 5.188394,0 9.394418,1.763817 9.394418,3.939595 z" + sodipodi:ry="3.939595" + sodipodi:rx="9.3944187" + sodipodi:cy="29.716238" + sodipodi:cx="-35.658386" + id="path1825-3-3" + style="color:#000000;fill:none;stroke:#7b7f7a;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dashoffset:0;marker:none;visibility:visible;display:inline;overflow:visible" + sodipodi:type="arc" /> + <path + sodipodi:type="arc" + style="color:#000000;fill:none;stroke:url(#linearGradient2005-3-2);stroke-width:0.68065339;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dashoffset:0;marker:none;visibility:visible;display:inline;overflow:visible" + id="path2983-5-7" + sodipodi:cx="-35.658386" + sodipodi:cy="29.716238" + sodipodi:rx="9.3944187" + sodipodi:ry="3.939595" + d="m -26.263968,29.716238 c 0,2.175778 -4.206024,3.939595 -9.394418,3.939595 -5.188394,0 -9.394419,-1.763817 -9.394419,-3.939595 0,-2.175778 4.206025,-3.939595 9.394419,-3.939595 5.188394,0 9.394418,1.763817 9.394418,3.939595 z" + transform="matrix(0.940273,0,0,0.940273,55.40361,3.521194)" /> + <path + sodipodi:nodetypes="ccccccccccccccccc" + style="fill:#d0d0d0;fill-opacity:1;fill-rule:evenodd;stroke:#979797;stroke-width:0.40000001;stroke-linecap:butt;stroke-linejoin:round;stroke-miterlimit:4;stroke-opacity:1" + d="m 25.6875,28.766243 -0.0625,1 c 0,0 4.324108,3.599166 9,4.202507 2.337946,0.30167 4.753675,0.702412 6.75,1.1875 1.996325,0.485088 3.588356,1.119606 4.125,1.65625 0.310411,0.310411 0.451063,0.573639 0.5,0.78125 0.04894,0.207611 0.03822,0.354815 -0.09375,0.5625 -0.263933,0.41537 -1.079857,0.967652 -2.46875,1.40625 C 40.659715,40.439695 35.717076,41 28.875,41 l 0,1 c 6.895998,0 11.863665,-0.527671 14.84375,-1.46875 1.490042,-0.47054 2.524942,-1.015687 3.03125,-1.8125 C 47.003154,38.320344 47.107321,37.830301 47,37.375 46.892679,36.919699 46.615445,36.490445 46.21875,36.09375 45.34118,35.21618 43.681912,34.68731 41.625,34.1875 39.568088,33.68769 37.109264,33.273171 34.75,32.96875 30.031473,32.359908 25.6875,28.766243 25.6875,28.766243 z" + id="path2411-4-7" + inkscape:connector-curvature="0" /> + <path + transform="matrix(1,0,0,1.368932,-1.978553,-19.02126)" + d="m 41.10058,35.051105 c 0,2.514001 -7.558406,4.552001 -16.882173,4.552001 -9.323767,0 -16.8821739,-2.038 -16.8821739,-4.552001 0,-2.514 7.5584069,-4.552 16.8821739,-4.552 9.323767,0 16.882173,2.038 16.882173,4.552 z" + sodipodi:ry="4.552" + sodipodi:rx="16.882174" + sodipodi:cy="35.051105" + sodipodi:cx="24.218407" + id="path2462-8-1" + style="color:#000000;fill:url(#radialGradient2007-9-2);fill-opacity:1;fill-rule:evenodd;stroke:none;stroke-width:1;marker:none;visibility:visible;display:inline;overflow:visible" + sodipodi:type="arc" /> + <rect + y="30.703611" + x="17.472397" + height="2.7400389" + width="9.0396729" + id="rect2699-7-2" + style="color:#000000;fill:url(#linearGradient2009-3-9);fill-opacity:1;fill-rule:evenodd;stroke:none;stroke-width:0.60872948;marker:none;visibility:visible;display:inline;overflow:visible" /> + <path + style="color:#000000;fill:url(#linearGradient2011-7-3);fill-opacity:1;fill-rule:evenodd;stroke:url(#linearGradient2013-8-3);stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dashoffset:0;marker:none;visibility:visible;display:inline;overflow:visible" + d="m 7.0809024,1.6956221 29.5881946,0 c 0.911342,0 1.624147,0.5834818 1.666752,1.401587 l 1.332044,25.5781139 c 0.05821,1.117735 -0.901056,2.020305 -2.020305,2.020305 l -31.545176,0 c -1.1192491,0 -2.078514,-0.90257 -2.0203052,-2.020305 L 5.4141506,3.0972091 c 0.040284,-0.7735346 0.5475027,-1.401587 1.6667518,-1.401587 z" + id="rect2404-3-1" + sodipodi:nodetypes="cssssssss" + inkscape:connector-curvature="0" /> + <path + sodipodi:nodetypes="ccccc" + id="path2377-3-0" + d="m 8.4105348,4.3058272 -1.242195,22.0453168 27.6503892,0 L 33.483712,4.3992558 8.4105348,4.3058272 z" + style="fill:url(#linearGradient2015-8-6);fill-opacity:1;fill-rule:evenodd;stroke:#000079;stroke-width:0.5;stroke-linecap:butt;stroke-linejoin:round;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" + inkscape:connector-curvature="0" /> + <path + style="fill:none;stroke:url(#linearGradient2017-3-8);stroke-width:0.99618119;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:0.24840764" + d="m 6.1774331,28.735789 31.4284769,0" + id="path2393-5-8" + inkscape:connector-curvature="0" /> + <path + sodipodi:nodetypes="cssssssss" + id="path2397-0-9" + d="M 6.9145985,2.7063396 36.760101,2.6685383 c 0.283697,-3.593e-4 0.559302,0.2372498 0.582105,0.6525438 L 38.704098,28.12433 c 0.05804,1.057031 -0.539749,1.785871 -1.598371,1.785871 l -30.5239687,0 c -1.0586228,0 -1.5930144,-0.728791 -1.5358714,-1.785871 L 6.3699773,3.6301633 C 6.4086732,2.9143326 6.5363627,2.7068187 6.9145985,2.7063396 z" + style="color:#000000;fill:none;stroke:url(#linearGradient2019-5-2);stroke-width:0.99999964;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:0.70063692;stroke-dashoffset:0;marker:none;visibility:visible;display:inline;overflow:visible" + inkscape:connector-curvature="0" /> + <path + sodipodi:nodetypes="ccccc" + style="opacity:0.53142856;fill:url(#linearGradient2021-8-6);fill-opacity:1;fill-rule:evenodd;stroke:none" + d="M 8.7115364,4.7463626 7.9090069,22.616693 C 18.953645,20.216063 19.33047,12.124494 33.063039,9.4699426 L 32.901567,4.8124267 8.7115364,4.7463626 z" + id="path2443-1-0" + inkscape:connector-curvature="0" /> + <path + transform="matrix(1.264398,0,0,1.291262,-6.216332,-4.000423)" + d="m 41.10058,35.051105 c 0,2.514001 -7.558406,4.552001 -16.882173,4.552001 -9.323767,0 -16.8821739,-2.038 -16.8821739,-4.552001 0,-2.514 7.5584069,-4.552 16.8821739,-4.552 9.323767,0 16.882173,2.038 16.882173,4.552 z" + sodipodi:ry="4.552" + sodipodi:rx="16.882174" + sodipodi:cy="35.051105" + sodipodi:cx="24.218407" + id="path2657-4-1" + style="color:#000000;fill:url(#radialGradient2023-3-9);fill-opacity:1;fill-rule:evenodd;stroke:none;stroke-width:1;marker:none;visibility:visible;display:inline;overflow:visible" + sodipodi:type="arc" /> + <path + sodipodi:nodetypes="cssssssss" + id="path2409-5-3" + d="m 6.4621839,36.817452 31.0024061,0 c 1.119249,0 0.977355,0.271438 1.092227,0.612846 l 2.834646,8.42481 c 0.114872,0.341409 0.02702,0.612846 -1.092227,0.612846 l -36.6716978,0 c -1.1192491,0 -1.2070995,-0.271437 -1.0922275,-0.612846 l 2.8346457,-8.42481 c 0.114872,-0.341409 -0.027022,-0.612846 1.0922275,-0.612846 z" + style="color:#000000;fill:url(#linearGradient2025-6-4);fill-opacity:1;fill-rule:evenodd;stroke:url(#linearGradient2027-7-6);stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0;marker:none;visibility:visible;display:inline;overflow:visible" + inkscape:connector-curvature="0" /> + <path + sodipodi:nodetypes="ccccccccc" + id="path2611-7-4" + d="m 6.3916892,38.829113 -1.7677669,5.126525 5.4800777,0 0.53033,-2.032932 14.849242,0 0.549679,2.075114 6.167835,0 -1.679378,-5.168707 -24.1300188,0 z" + style="fill:#7a7d77;fill-opacity:1;fill-rule:evenodd;stroke:none" + inkscape:connector-curvature="0" /> + <path + id="path2613-0-8" + d="m 11.076272,42.27626 -0.441942,1.679379 14.760854,0 -0.441942,-1.767767 -13.87697,0.08839 z" + style="fill:#777874;fill-opacity:1;fill-rule:evenodd;stroke:none" + inkscape:connector-curvature="0" /> + <path + style="color:#000000;fill:#777a75;fill-opacity:1;fill-rule:evenodd;stroke:none;stroke-width:0.25pt;marker:none;visibility:visible;display:inline;overflow:visible" + d="m 37.592776,38.829114 1.679379,5.038136 -5.480078,-0.08839 -1.502602,-4.861359 5.303301,-0.08839 z" + id="path2619-7-5" + inkscape:connector-curvature="0" /> + <path + id="path2615-8-8" + d="m 37.592776,38.298786 1.679379,5.038136 -5.480078,-0.08839 -1.502602,-4.861359 5.303301,-0.08839 z" + style="color:#000000;fill:url(#linearGradient2029-8-8);fill-opacity:1;fill-rule:evenodd;stroke:none;stroke-width:0.25pt;marker:none;visibility:visible;display:inline;overflow:visible" + inkscape:connector-curvature="0" /> + <path + style="fill:url(#linearGradient2031-6-6);fill-opacity:1;fill-rule:evenodd;stroke:none" + d="m 6.3916892,38.210397 -1.7677669,5.126525 5.4800777,0 0.53033,-2.032932 14.849242,0 0.549679,2.075114 6.167835,0 -1.679378,-5.168707 -24.1300188,0 z" + id="path2617-9-2" + sodipodi:nodetypes="ccccccccc" + inkscape:connector-curvature="0" /> + <path + style="color:#000000;fill:url(#linearGradient2033-2-2);fill-opacity:1;fill-rule:evenodd;stroke:none;stroke-width:0.25pt;marker:none;visibility:visible;display:inline;overflow:visible" + d="m 11.076272,41.745932 -0.441942,1.679379 14.760854,0 -0.441942,-1.767767 -13.87697,0.08839 z" + id="path2621-9-2" + inkscape:connector-curvature="0" /> + <path + style="color:#000000;fill:none;stroke:url(#linearGradient2035-9-2);stroke-width:0.5;stroke-linecap:butt;stroke-linejoin:round;stroke-miterlimit:4;stroke-opacity:1;stroke-dashoffset:0;marker:none;visibility:visible;display:inline;overflow:visible" + d="m 6.1278189,37.578116 31.8258151,0 2.637179,8.092563 -37.2610701,0 2.798076,-8.092563 z" + id="path2631-3-0" + sodipodi:nodetypes="ccccc" + inkscape:connector-curvature="0" /> + <path + transform="matrix(1.331237,0,0,0.658449,-10.41933,2.853866)" + d="m 35.620504,3.9384086 c 0,0.4637476 -0.375941,0.8396893 -0.839689,0.8396893 -0.463747,0 -0.839689,-0.3759417 -0.839689,-0.8396893 0,-0.4637476 0.375942,-0.8396893 0.839689,-0.8396893 0.463748,0 0.839689,0.3759417 0.839689,0.8396893 z" + sodipodi:ry="0.83968931" + sodipodi:rx="0.83968931" + sodipodi:cy="3.9384086" + sodipodi:cx="34.780815" + id="path2709-9-6" + style="color:#000000;fill:url(#linearGradient2037-7-4);fill-opacity:1;fill-rule:evenodd;stroke:none;stroke-width:0.5;marker:none;visibility:visible;display:inline;overflow:visible" + sodipodi:type="arc" /> + <path + sodipodi:type="arc" + style="color:#000000;fill:url(#linearGradient2039-1-4);fill-opacity:1;fill-rule:evenodd;stroke:none;stroke-width:0.5;marker:none;visibility:visible;display:inline;overflow:visible" + id="path2719-4-3" + sodipodi:cx="34.780815" + sodipodi:cy="3.9384086" + sodipodi:rx="0.83968931" + sodipodi:ry="0.83968931" + d="m 35.620504,3.9384086 c 0,0.4637476 -0.375941,0.8396893 -0.839689,0.8396893 -0.463747,0 -0.839689,-0.3759417 -0.839689,-0.8396893 0,-0.4637476 0.375942,-0.8396893 0.839689,-0.8396893 0.463748,0 0.839689,0.3759417 0.839689,0.8396893 z" + transform="matrix(1.331237,0,0,0.658449,-10.30573,4.959651)" /> + <path + transform="matrix(1.331237,0,0,0.658449,-10.19213,6.959651)" + d="m 35.620504,3.9384086 c 0,0.4637476 -0.375941,0.8396893 -0.839689,0.8396893 -0.463747,0 -0.839689,-0.3759417 -0.839689,-0.8396893 0,-0.4637476 0.375942,-0.8396893 0.839689,-0.8396893 0.463748,0 0.839689,0.3759417 0.839689,0.8396893 z" + sodipodi:ry="0.83968931" + sodipodi:rx="0.83968931" + sodipodi:cy="3.9384086" + sodipodi:cx="34.780815" + id="path2723-6-6" + style="color:#000000;fill:url(#linearGradient2041-7-6);fill-opacity:1;fill-rule:evenodd;stroke:none;stroke-width:0.5;marker:none;visibility:visible;display:inline;overflow:visible" + sodipodi:type="arc" /> + <path + sodipodi:type="arc" + style="color:#000000;fill:url(#linearGradient2043-8-4);fill-opacity:1;fill-rule:evenodd;stroke:none;stroke-width:0.5;marker:none;visibility:visible;display:inline;overflow:visible" + id="path2727-4-1" + sodipodi:cx="34.780815" + sodipodi:cy="3.9384086" + sodipodi:rx="0.83968931" + sodipodi:ry="0.83968931" + d="m 35.620504,3.9384086 c 0,0.4637476 -0.375941,0.8396893 -0.839689,0.8396893 -0.463747,0 -0.839689,-0.3759417 -0.839689,-0.8396893 0,-0.4637476 0.375942,-0.8396893 0.839689,-0.8396893 0.463748,0 0.839689,0.3759417 0.839689,0.8396893 z" + transform="matrix(1.331237,0,0,0.658449,-10.07853,8.959651)" /> + <path + transform="matrix(1.331237,0,0,0.658449,-9.96493,10.95965)" + d="m 35.620504,3.9384086 c 0,0.4637476 -0.375941,0.8396893 -0.839689,0.8396893 -0.463747,0 -0.839689,-0.3759417 -0.839689,-0.8396893 0,-0.4637476 0.375942,-0.8396893 0.839689,-0.8396893 0.463748,0 0.839689,0.3759417 0.839689,0.8396893 z" + sodipodi:ry="0.83968931" + sodipodi:rx="0.83968931" + sodipodi:cy="3.9384086" + sodipodi:cx="34.780815" + id="path2731-5-0" + style="color:#000000;fill:url(#linearGradient2045-9-2);fill-opacity:1;fill-rule:evenodd;stroke:none;stroke-width:0.5;marker:none;visibility:visible;display:inline;overflow:visible" + sodipodi:type="arc" /> + <path + id="text2735-5-5" + d="m 20,27.317666 0.281716,0 c 0.08376,1e-6 0.147985,0.01866 0.19266,0.05599 0.04497,0.03703 0.06745,0.08994 0.06745,0.158714 -1e-6,0.06907 -0.02248,0.122268 -0.06745,0.159595 -0.04467,0.03703 -0.108895,0.05555 -0.19266,0.05555 l -0.111981,0 0,0.22837 -0.169735,0 0,-0.658219 m 0.169735,0.123003 0,0.183843 0.0939,0 c 0.03292,0 0.05834,-0.0079 0.07627,-0.02381 0.01793,-0.01617 0.02689,-0.03894 0.02689,-0.06834 0,-0.02939 -0.009,-0.05202 -0.02689,-0.06789 -0.01793,-0.01587 -0.04335,-0.02381 -0.07627,-0.02381 l -0.0939,0 m 0.792244,-0.0119 c -0.05173,1e-6 -0.09185,0.01911 -0.120358,0.05731 -0.02851,0.03821 -0.04276,0.092 -0.04276,0.161359 0,0.06907 0.01425,0.122709 0.04276,0.160918 0.02851,0.03821 0.06863,0.05731 0.120358,0.05731 0.05202,0 0.09229,-0.0191 0.120799,-0.05731 0.02851,-0.03821 0.04276,-0.09185 0.04276,-0.160918 -10e-7,-0.06936 -0.01425,-0.123149 -0.04276,-0.161359 -0.02851,-0.03821 -0.06878,-0.05731 -0.120799,-0.05731 m 0,-0.123003 c 0.105808,1e-6 0.188692,0.03027 0.248651,0.09082 0.05996,0.06055 0.08994,0.144165 0.08994,0.250855 -1e-6,0.106397 -0.02998,0.189868 -0.08994,0.250414 -0.05996,0.06055 -0.142843,0.09082 -0.248651,0.09082 -0.105515,0 -0.188399,-0.03027 -0.248651,-0.09082 -0.05996,-0.06055 -0.08994,-0.144017 -0.08994,-0.250414 0,-0.10669 0.02998,-0.190309 0.08994,-0.250855 0.06025,-0.06055 0.143136,-0.09082 0.248651,-0.09082 m 0.466441,0.0119 0.189574,0 0.239393,0.451451 0,-0.451451 0.160918,0 0,0.658219 -0.189575,0 -0.239392,-0.451451 0,0.451451 -0.160918,0 0,-0.658219 m 0.663069,0 0.185606,0 0.149896,0.234543 0.149896,-0.234543 0.186048,0 -0.250856,0.380912 0,0.277307 -0.169735,0 0,-0.277307 -0.250855,-0.380912" + style="font-size:0.9029026px;font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;writing-mode:lr-tb;text-anchor:start;fill:#4a4a4a;fill-opacity:1;stroke:none;font-family:Bitstream Vera Sans" + inkscape:connector-curvature="0" /> + </g> + </g> + <g + id="g3827"> + <path + inkscape:connector-curvature="0" + id="path5647-1-4" + d="m 830.32618,790.03857 c 25.6904,-33.65986 25.6904,-33.65986 25.6904,-33.65986" + style="opacity:0.90000006;fill:none;stroke:#030000;stroke-width:1.76822448;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" /> + <path + inkscape:connector-curvature="0" + id="path5649-2-2" + d="m 856.24525,756.16184 c 0,6.74697 0,6.74697 0,6.74697" + style="opacity:0.90000006;fill:none;stroke:#030000;stroke-width:1.76822448;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" /> + <path + inkscape:connector-curvature="0" + id="path5649-8-9-0" + d="m 856.21292,756.11436 c -5.14952,0 -5.14952,0 -5.14952,0" + style="opacity:0.90000006;fill:none;stroke:#030000;stroke-width:1.76822448;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" /> + </g> + <g + id="g5722-7-0" + transform="matrix(0.29032369,-0.10566918,0.13844899,0.38038547,594.73803,551.66662)"> + <path + inkscape:connector-curvature="0" + id="path5647-1-4-3" + d="m 669.99529,844.65261 c 83.15229,-83.1523 83.15229,-83.1523 83.15229,-83.1523" + style="opacity:0.90000006;fill:none;stroke:#030000;stroke-width:5;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" /> + <path + inkscape:connector-curvature="0" + id="path5649-2-2-3" + d="m 753.88771,760.96455 c 0,16.66751 0,16.66751 0,16.66751" + style="opacity:0.90000006;fill:none;stroke:#030000;stroke-width:5;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" /> + <path + inkscape:connector-curvature="0" + id="path5649-8-9-0-9" + d="m 753.78309,760.84726 c -16.6675,0 -16.6675,0 -16.6675,0" + style="opacity:0.90000006;fill:none;stroke:#030000;stroke-width:5;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" /> + </g> + <g + id="g5722-7-04" + transform="matrix(0.15447801,-0.26756376,0.35056515,0.20239888,581.41817,807.87524)"> + <path + inkscape:connector-curvature="0" + id="path5647-1-4-33" + d="m 669.99529,844.65261 c 83.15229,-83.1523 83.15229,-83.1523 83.15229,-83.1523" + style="opacity:0.90000006;fill:none;stroke:#030000;stroke-width:5;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" /> + <path + inkscape:connector-curvature="0" + id="path5649-2-2-4" + d="m 753.88771,760.96455 c 0,16.66751 0,16.66751 0,16.66751" + style="opacity:0.90000006;fill:none;stroke:#030000;stroke-width:5;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" /> + <path + inkscape:connector-curvature="0" + id="path5649-8-9-0-2" + d="m 753.78309,760.84726 c -16.6675,0 -16.6675,0 -16.6675,0" + style="opacity:0.90000006;fill:none;stroke:#030000;stroke-width:5;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" /> + </g> + <g + transform="matrix(-1,0,0,-1,1685.5536,1546.8494)" + id="g3827-3"> + <path + inkscape:connector-curvature="0" + id="path5647-1-4-2" + d="m 830.32618,790.03857 c 25.6904,-33.65986 25.6904,-33.65986 25.6904,-33.65986" + style="opacity:0.90000006;fill:none;stroke:#030000;stroke-width:1.76822448;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" /> + <path + inkscape:connector-curvature="0" + id="path5649-2-2-0" + d="m 856.24525,756.16184 c 0,6.74697 0,6.74697 0,6.74697" + style="opacity:0.90000006;fill:none;stroke:#030000;stroke-width:1.76822448;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" /> + <path + inkscape:connector-curvature="0" + id="path5649-8-9-0-6" + d="m 856.21292,756.11436 c -5.14952,0 -5.14952,0 -5.14952,0" + style="opacity:0.90000006;fill:none;stroke:#030000;stroke-width:1.76822448;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" /> + </g> + <g + id="g5722-7-0-1" + transform="matrix(-0.29032369,0.10566918,-0.13844899,-0.38038547,1230.2287,1012.1938)"> + <path + inkscape:connector-curvature="0" + id="path5647-1-4-3-5" + d="m 669.99529,844.65261 c 83.15229,-83.1523 83.15229,-83.1523 83.15229,-83.1523" + style="opacity:0.90000006;fill:none;stroke:#030000;stroke-width:5;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" /> + <path + inkscape:connector-curvature="0" + id="path5649-2-2-3-5" + d="m 753.88771,760.96455 c 0,16.66751 0,16.66751 0,16.66751" + style="opacity:0.90000006;fill:none;stroke:#030000;stroke-width:5;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" /> + <path + inkscape:connector-curvature="0" + id="path5649-8-9-0-9-4" + d="m 753.78309,760.84726 c -16.6675,0 -16.6675,0 -16.6675,0" + style="opacity:0.90000006;fill:none;stroke:#030000;stroke-width:5;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" /> + </g> + <g + id="g5722-7-04-7" + transform="matrix(-0.15447801,0.26756376,-0.35056515,-0.20239888,1364.2001,751.75086)"> + <path + inkscape:connector-curvature="0" + id="path5647-1-4-33-6" + d="m 669.99529,844.65261 c 83.15229,-83.1523 83.15229,-83.1523 83.15229,-83.1523" + style="opacity:0.90000006;fill:none;stroke:#030000;stroke-width:5;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" /> + <path + inkscape:connector-curvature="0" + id="path5649-2-2-4-5" + d="m 753.88771,760.96455 c 0,16.66751 0,16.66751 0,16.66751" + style="opacity:0.90000006;fill:none;stroke:#030000;stroke-width:5;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" /> + <path + inkscape:connector-curvature="0" + id="path5649-8-9-0-2-6" + d="m 753.78309,760.84726 c -16.6675,0 -16.6675,0 -16.6675,0" + style="opacity:0.90000006;fill:none;stroke:#030000;stroke-width:5;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" /> + </g> + </g> +</svg> diff --git a/man/html/images/tngconsole.png b/man/html/images/tngconsole.png Binary files differnew file mode 100644 index 0000000..6a733e1 --- /dev/null +++ b/man/html/images/tngconsole.png diff --git a/man/html/images/trace_1.png b/man/html/images/trace_1.png Binary files differnew file mode 100644 index 0000000..deceec1 --- /dev/null +++ b/man/html/images/trace_1.png diff --git a/man/html/images/trace_buffer.png b/man/html/images/trace_buffer.png Binary files differnew file mode 100644 index 0000000..a069d52 --- /dev/null +++ b/man/html/images/trace_buffer.png diff --git a/man/html/images/trace_example.png b/man/html/images/trace_example.png Binary files differnew file mode 100644 index 0000000..37d29f7 --- /dev/null +++ b/man/html/images/trace_example.png diff --git a/man/html/images/trace_libpcp.png b/man/html/images/trace_libpcp.png Binary files differnew file mode 100644 index 0000000..5a4c38d --- /dev/null +++ b/man/html/images/trace_libpcp.png diff --git a/man/html/images/xenln.png b/man/html/images/xenln.png Binary files differnew file mode 100644 index 0000000..8895c34 --- /dev/null +++ b/man/html/images/xenln.png diff --git a/man/html/images/xnmevents.png b/man/html/images/xnmevents.png Binary files differnew file mode 100644 index 0000000..7b60aec --- /dev/null +++ b/man/html/images/xnmevents.png diff --git a/man/html/importdata/GNUmakefile b/man/html/importdata/GNUmakefile new file mode 100644 index 0000000..2fa2570 --- /dev/null +++ b/man/html/importdata/GNUmakefile @@ -0,0 +1,20 @@ +TOPDIR = ../../.. +include $(TOPDIR)/src/include/builddefs + +BUNDLE = importdata +SCRIPT = mover2pcp +LSRCFILES = $(SCRIPT) \ + README moverv1 moverv2 moverv3 moverv4 \ + mk.mover.log mover.log + +default: + +include $(BUILDRULES) + +install install-dev: default + $(INSTALL) -m 755 -d $(PCP_BOOKS_DIR)/html/$(BUNDLE) + $(INSTALL) -m 644 $(SCRIPT) $(PCP_BOOKS_DIR)/html/$(BUNDLE)/$(SCRIPT) + +default_pcp : default + +install_pcp : install diff --git a/man/html/importdata/README b/man/html/importdata/README new file mode 100644 index 0000000..befc9e2 --- /dev/null +++ b/man/html/importdata/README @@ -0,0 +1,9 @@ +mover2pcp - example used in lab.importdata.html in pcp-doc + + mover.log - sample log file + mk.mover.log - script to create fake mover.log + moverv1 - minimalist version 1 + moverv2 - minimalist version 2 + moverv3 - minimalist version 3 + moverv4 - minimalist version 4 + mover2pcp - final script diff --git a/man/html/importdata/mk.mover.log b/man/html/importdata/mk.mover.log new file mode 100755 index 0000000..0d182d6 --- /dev/null +++ b/man/html/importdata/mk.mover.log @@ -0,0 +1,35 @@ +#!/bin/sh +# +# Generate a mover.log to be used with mover2pcp +# + +find $HOME -type f \ +| sed -e 5000q \ +| while read f +do + stat --format="%n %s" "$f" +done \ +| awk ' +BEGIN { now = systime(); start = now - 30*24*3600 + maxbatch = 60; + want = int(rand()*maxbatch); + n = c[0] = c[1] = c[2] = max_b = b = 0 + } + #debug# { print } + { want--; + if (want < 0) { + if (rand() < 0.15) { + # 15% of the time, output a no activity line + n = c[0] = c[1] = c[2] = max_b = b = 0 + } + printf "%s %d files (%d, %d, %d) %d bytes (%d)\n", strftime("%Y-%m-%d %H:%M:%S", start), n, c[0], c[1], c[2], b, max_b + start += 30; + want = int(rand()*maxbatch); + n = c[0] = c[1] = c[2] = max_b = b = 0 + } + n++; b += $2 + if ($2 <= 1024) c[0]++ + else if ($2 <= 1024*1024) c[1]++ + else c[2]++ + if ($2 > max_b) max_b = $2 + }' diff --git a/man/html/importdata/mover.log b/man/html/importdata/mover.log new file mode 100644 index 0000000..70700cd --- /dev/null +++ b/man/html/importdata/mover.log @@ -0,0 +1,161 @@ +2010-07-04 13:46:29 14 files (6, 8, 0) 142512 bytes (92098) +2010-07-04 13:46:59 51 files (28, 23, 0) 132761 bytes (33239) +2010-07-04 13:47:29 36 files (23, 12, 1) 5733152 bytes (5688400) +2010-07-04 13:47:59 49 files (40, 9, 0) 118418 bytes (70669) +2010-07-04 13:48:29 30 files (7, 23, 0) 210531 bytes (52261) +2010-07-04 13:48:59 23 files (6, 17, 0) 81048 bytes (15175) +2010-07-04 13:49:29 55 files (31, 24, 0) 190841 bytes (27908) +2010-07-04 13:49:59 54 files (49, 5, 0) 14078 bytes (1213) +2010-07-04 13:50:29 38 files (19, 19, 0) 82398 bytes (16781) +2010-07-04 13:50:59 0 files (0, 0, 0) 0 bytes (0) +2010-07-04 13:51:29 31 files (8, 23, 0) 202755 bytes (41984) +2010-07-04 13:51:59 0 files (0, 0, 0) 0 bytes (0) +2010-07-04 13:52:29 7 files (4, 3, 0) 15954 bytes (8789) +2010-07-04 13:52:59 1 files (1, 0, 0) 719 bytes (719) +2010-07-04 13:53:29 7 files (2, 5, 0) 28976 bytes (10804) +2010-07-04 13:53:59 16 files (5, 11, 0) 619501 bytes (471054) +2010-07-04 13:54:29 54 files (24, 28, 2) 4097068 bytes (1451420) +2010-07-04 13:54:59 44 files (11, 33, 0) 280558 bytes (35925) +2010-07-04 13:55:29 56 files (16, 40, 0) 209611 bytes (27890) +2010-07-04 13:55:59 54 files (13, 41, 0) 265851 bytes (23801) +2010-07-04 13:56:29 20 files (5, 15, 0) 63906 bytes (21526) +2010-07-04 13:56:59 60 files (19, 41, 0) 149357 bytes (59852) +2010-07-04 13:57:29 43 files (13, 30, 0) 204814 bytes (105994) +2010-07-04 13:57:59 57 files (20, 37, 0) 257186 bytes (30296) +2010-07-04 13:58:29 7 files (2, 5, 0) 47402 bytes (28647) +2010-07-04 13:58:59 34 files (17, 17, 0) 110547 bytes (43668) +2010-07-04 13:59:29 5 files (0, 5, 0) 16039 bytes (5628) +2010-07-04 13:59:59 12 files (1, 11, 0) 92010 bytes (19725) +2010-07-04 14:00:29 39 files (11, 28, 0) 224461 bytes (78750) +2010-07-04 14:00:59 3 files (1, 2, 0) 3257 bytes (2123) +2010-07-04 14:01:29 0 files (0, 0, 0) 0 bytes (0) +2010-07-04 14:01:59 10 files (3, 7, 0) 22664 bytes (8319) +2010-07-04 14:02:29 42 files (15, 27, 0) 158907 bytes (63403) +2010-07-04 14:02:59 42 files (14, 28, 0) 179235 bytes (45308) +2010-07-04 14:03:29 28 files (4, 24, 0) 89672 bytes (21398) +2010-07-04 14:03:59 28 files (3, 25, 0) 410717 bytes (221626) +2010-07-04 14:04:29 6 files (0, 6, 0) 20810 bytes (5443) +2010-07-04 14:04:59 57 files (8, 49, 0) 242260 bytes (40168) +2010-07-04 14:05:29 0 files (0, 0, 0) 0 bytes (0) +2010-07-04 14:05:59 15 files (6, 9, 0) 61522 bytes (14739) +2010-07-04 14:06:29 27 files (11, 16, 0) 146905 bytes (86884) +2010-07-04 14:06:59 53 files (16, 37, 0) 272658 bytes (103530) +2010-07-04 14:07:29 57 files (1, 56, 0) 672539 bytes (66131) +2010-07-04 14:07:59 51 files (24, 27, 0) 197605 bytes (48368) +2010-07-04 14:08:29 36 files (23, 13, 0) 220569 bytes (53235) +2010-07-04 14:08:59 20 files (0, 20, 0) 141069 bytes (31880) +2010-07-04 14:09:29 55 files (1, 54, 0) 335190 bytes (30038) +2010-07-04 14:09:59 51 files (0, 51, 0) 189665 bytes (17426) +2010-07-04 14:10:29 30 files (0, 30, 0) 126407 bytes (16961) +2010-07-04 14:10:59 0 files (0, 0, 0) 0 bytes (0) +2010-07-04 14:11:29 26 files (3, 23, 0) 440333 bytes (295831) +2010-07-04 14:11:59 7 files (6, 1, 0) 5362 bytes (2892) +2010-07-04 14:12:29 38 files (25, 13, 0) 83338 bytes (19874) +2010-07-04 14:12:59 47 files (21, 26, 0) 146862 bytes (21194) +2010-07-04 14:13:29 60 files (35, 25, 0) 110686 bytes (30581) +2010-07-04 14:13:59 39 files (19, 20, 0) 75524 bytes (13688) +2010-07-04 14:14:29 58 files (36, 22, 0) 158258 bytes (33037) +2010-07-04 14:14:59 14 files (2, 11, 1) 6739584 bytes (4808802) +2010-07-04 14:15:29 0 files (0, 0, 0) 0 bytes (0) +2010-07-04 14:15:59 17 files (8, 9, 0) 35206 bytes (12257) +2010-07-04 14:16:29 23 files (11, 12, 0) 82701 bytes (27815) +2010-07-04 14:16:59 53 files (31, 22, 0) 83209 bytes (13686) +2010-07-04 14:17:29 60 files (35, 25, 0) 125315 bytes (21077) +2010-07-04 14:17:59 33 files (20, 13, 0) 41639 bytes (9772) +2010-07-04 14:18:29 47 files (29, 18, 0) 91435 bytes (21920) +2010-07-04 14:18:59 44 files (28, 16, 0) 88960 bytes (21124) +2010-07-04 14:19:29 29 files (22, 7, 0) 67806 bytes (22687) +2010-07-04 14:19:59 52 files (35, 17, 0) 48792 bytes (6431) +2010-07-04 14:20:29 24 files (16, 8, 0) 64065 bytes (30170) +2010-07-04 14:20:59 13 files (8, 5, 0) 23280 bytes (13729) +2010-07-04 14:21:29 21 files (15, 6, 0) 22200 bytes (5657) +2010-07-04 14:21:59 27 files (16, 11, 0) 55662 bytes (21158) +2010-07-04 14:22:29 39 files (23, 16, 0) 126781 bytes (20554) +2010-07-04 14:22:59 54 files (36, 18, 0) 122433 bytes (21976) +2010-07-04 14:23:29 39 files (28, 11, 0) 616714 bytes (439081) +2010-07-04 14:23:59 0 files (0, 0, 0) 0 bytes (0) +2010-07-04 14:24:29 37 files (8, 29, 0) 204193 bytes (36438) +2010-07-04 14:24:59 21 files (2, 19, 0) 196555 bytes (27156) +2010-07-04 14:25:29 25 files (7, 16, 2) 22880215 bytes (12439460) +2010-07-04 14:25:59 59 files (9, 50, 0) 1375709 bytes (365788) +2010-07-04 14:26:29 41 files (0, 41, 0) 187455 bytes (37965) +2010-07-04 14:26:59 52 files (0, 52, 0) 311272 bytes (40326) +2010-07-04 14:27:29 37 files (3, 34, 0) 1272456 bytes (502112) +2010-07-04 14:27:59 9 files (0, 9, 0) 55111 bytes (16345) +2010-07-04 14:28:29 23 files (0, 23, 0) 128851 bytes (18182) +2010-07-04 14:28:59 39 files (5, 34, 0) 129389 bytes (18724) +2010-07-04 14:29:29 34 files (2, 32, 0) 219142 bytes (44562) +2010-07-04 14:29:59 58 files (5, 53, 0) 630739 bytes (118843) +2010-07-04 14:30:29 26 files (13, 13, 0) 50311 bytes (14925) +2010-07-04 14:30:59 57 files (39, 17, 1) 5712423 bytes (5561008) +2010-07-04 14:31:29 0 files (0, 0, 0) 0 bytes (0) +2010-07-04 14:31:59 58 files (2, 56, 0) 397563 bytes (30632) +2010-07-04 14:32:29 45 files (0, 45, 0) 414913 bytes (37794) +2010-07-04 14:32:59 34 files (6, 28, 0) 256229 bytes (35787) +2010-07-04 14:33:29 43 files (16, 27, 0) 233841 bytes (37056) +2010-07-04 14:33:59 30 files (14, 16, 0) 55166 bytes (8639) +2010-07-04 14:34:29 44 files (5, 39, 0) 396444 bytes (71954) +2010-07-04 14:34:59 0 files (0, 0, 0) 0 bytes (0) +2010-07-04 14:35:29 3 files (1, 2, 0) 4285 bytes (2847) +2010-07-04 14:35:59 51 files (18, 33, 0) 341742 bytes (81285) +2010-07-04 14:36:29 36 files (9, 26, 1) 1779423 bytes (1309108) +2010-07-04 14:36:59 8 files (0, 8, 0) 77751 bytes (22172) +2010-07-04 14:37:29 2 files (0, 2, 0) 42270 bytes (36992) +2010-07-04 14:37:59 21 files (0, 21, 0) 196535 bytes (30632) +2010-07-04 14:38:29 30 files (0, 30, 0) 244081 bytes (56840) +2010-07-04 14:38:59 14 files (1, 13, 0) 156581 bytes (39576) +2010-07-04 14:39:29 21 files (1, 20, 0) 176378 bytes (22528) +2010-07-04 14:39:59 47 files (1, 46, 0) 472401 bytes (37794) +2010-07-04 14:40:29 19 files (0, 19, 0) 258176 bytes (41172) +2010-07-04 14:40:59 55 files (5, 50, 0) 547908 bytes (41113) +2010-07-04 14:41:29 35 files (5, 30, 0) 797776 bytes (205952) +2010-07-04 14:41:59 2 files (0, 2, 0) 15628 bytes (8584) +2010-07-04 14:42:29 31 files (7, 24, 0) 714775 bytes (430807) +2010-07-04 14:42:59 38 files (10, 28, 0) 340243 bytes (86242) +2010-07-04 14:43:29 0 files (0, 0, 0) 0 bytes (0) +2010-07-04 14:43:59 51 files (3, 48, 0) 729936 bytes (102096) +2010-07-04 14:44:29 0 files (0, 0, 0) 0 bytes (0) +2010-07-04 14:44:59 40 files (19, 21, 0) 199313 bytes (49400) +2010-07-04 14:45:29 26 files (1, 25, 0) 373460 bytes (76020) +2010-07-04 14:45:59 17 files (2, 15, 0) 160348 bytes (53724) +2010-07-04 14:46:29 21 files (7, 14, 0) 218240 bytes (81617) +2010-07-04 14:46:59 3 files (2, 1, 0) 3035 bytes (1961) +2010-07-04 14:47:29 51 files (15, 36, 0) 380236 bytes (58229) +2010-07-04 14:47:59 8 files (1, 7, 0) 111551 bytes (47836) +2010-07-04 14:48:29 0 files (0, 0, 0) 0 bytes (0) +2010-07-04 14:48:59 36 files (8, 28, 0) 349285 bytes (47973) +2010-07-04 14:49:29 0 files (0, 0, 0) 0 bytes (0) +2010-07-04 14:49:59 0 files (0, 0, 0) 0 bytes (0) +2010-07-04 14:50:29 0 files (0, 0, 0) 0 bytes (0) +2010-07-04 14:50:59 14 files (3, 11, 0) 306151 bytes (150867) +2010-07-04 14:51:29 0 files (0, 0, 0) 0 bytes (0) +2010-07-04 14:51:59 17 files (0, 17, 0) 560532 bytes (102773) +2010-07-04 14:52:29 40 files (9, 31, 0) 700198 bytes (171887) +2010-07-04 14:52:59 15 files (7, 7, 1) 2365905 bytes (2170898) +2010-07-04 14:53:29 0 files (0, 0, 0) 0 bytes (0) +2010-07-04 14:53:59 3 files (0, 3, 0) 21068 bytes (18393) +2010-07-04 14:54:29 56 files (12, 44, 0) 588239 bytes (65080) +2010-07-04 14:54:59 2 files (0, 2, 0) 13714 bytes (12623) +2010-07-04 14:55:29 9 files (0, 9, 0) 93199 bytes (30398) +2010-07-04 14:55:59 19 files (5, 14, 0) 275232 bytes (46694) +2010-07-04 14:56:29 17 files (6, 11, 0) 259098 bytes (60240) +2010-07-04 14:56:59 0 files (0, 0, 0) 0 bytes (0) +2010-07-04 14:57:29 39 files (11, 28, 0) 1666180 bytes (640932) +2010-07-04 14:57:59 22 files (0, 22, 0) 752584 bytes (102773) +2010-07-04 14:58:29 14 files (3, 11, 0) 313501 bytes (96965) +2010-07-04 14:58:59 0 files (0, 0, 0) 0 bytes (0) +2010-07-04 14:59:29 7 files (0, 7, 0) 133949 bytes (74888) +2010-07-04 14:59:59 10 files (2, 8, 0) 33537 bytes (7069) +2010-07-04 15:00:29 34 files (20, 14, 0) 242703 bytes (171887) +2010-07-04 15:00:59 26 files (20, 6, 0) 52686 bytes (18979) +2010-07-04 15:01:29 13 files (8, 5, 0) 26281 bytes (7141) +2010-07-04 15:01:59 11 files (5, 5, 1) 2061332 bytes (1903984) +2010-07-04 15:02:29 49 files (24, 25, 0) 378404 bytes (203072) +2010-07-04 15:02:59 40 files (17, 23, 0) 86640 bytes (11000) +2010-07-04 15:03:29 19 files (9, 10, 0) 128134 bytes (82733) +2010-07-04 15:03:59 18 files (13, 4, 1) 5854464 bytes (5359033) +2010-07-04 15:04:29 49 files (25, 24, 0) 249161 bytes (109605) +2010-07-04 15:04:59 42 files (11, 31, 0) 1508473 bytes (1041876) +2010-07-04 15:05:29 17 files (0, 17, 0) 191522 bytes (36384) +2010-07-04 15:05:59 0 files (0, 0, 0) 0 bytes (0) +2010-07-04 15:06:29 9 files (1, 8, 0) 58844 bytes (16627) diff --git a/man/html/importdata/mover2pcp b/man/html/importdata/mover2pcp new file mode 100755 index 0000000..8d45e1a --- /dev/null +++ b/man/html/importdata/mover2pcp @@ -0,0 +1,277 @@ +#!/usr/bin/perl +# +# Import mover.log data and create a PCP archive +# +# mover.log lines ... +# 2010-07-04 13:50:32 54 files (24, 28, 2) 4097068 bytes (1451420) +# date +# time +# number of files moved +# number with size <= 1K +# number with size <= 1M +# number with size >1M +# aggregate size of moved files +# max file size +# +# Copyright (c) 2010 Ken McDonell. All Rights Reserved. +# +# This program is free software; you can redistribute it and/or modify it +# under the terms of the GNU General Public License as published by the +# Free Software Foundation; either version 2 of the License, or (at your +# option) any later version. +# +# This program is distributed in the hope that it will be useful, but +# WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +# or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +# for more details. +# + +use strict; +use warnings; + +use Getopt::Std; +use Date::Parse; +use Date::Format; +use PCP::LogImport; + +my $line = 0; # input line number +my $basedate = undef; +my $basetime = "00:00:00"; +my $host = undef; +my $zone = "UTC"; # default timezone unless -Z on command line +my $sts; +my %options; # for command line arguments +my @handle = (); # pmi* handles, one per metric-instance pair +my $h = 0; # index into handle[] +my %inst_map = (); # key=indom value=last_inst_assigned, and + # key=indom.instance value=inst +my $putsts = 0; # pmiPutValue() errors are only checked @ end of loop +my $sz_indom = pmInDom_build(PMI_DOMAIN, 0); +my $nfile = 0; +my $nbyte = 0; +my @nfile_by_size = (0,0,0); + +# Initialize the PCP archive label fields +# +# PCP expects a $TZ style timezone in the archive label, so we have +# to make up a PCP-xx:xx timezone. +# Note this involves a sign reversal! +# +sub do_label() +{ + my $label_zone = $zone; + if ($zone =~ /^[-+][0-9][0-9][0-9][0-9]/) { + $label_zone =~ s/^\+/PCP-/; + $label_zone =~ s/^-/PCP+/; + $label_zone =~ s/(..)$/:$1/; + } + elsif ($zone ne "UTC") { + print "mover2pcp: Warning: unexpected timezone ($zone), reverting to UTC\n"; + $zone = "UTC"; + $label_zone = "UTC"; + } + pmiSetTimezone($label_zone) >= 0 + or die "pmiSetTimezone($label_zone): " . pmiErrStr(-1) . "\n"; + + if (defined($host)) { + pmiSetHostname($host) >= 0 + or die "pmiSetHostname($host): " . pmiErrStr(-1) . "\n"; + } +} + +# Handle metrics with the a singular value, calling pmiAddMetric() and +# pmiGetHandle() +# +sub def_single($) +{ + my ($name) = @_; + my $sts; + my $type = PM_TYPE_U32; + my $sem = PM_SEM_COUNTER; + my $units = pmiUnits(1,0,0,PM_SPACE_BYTE,0,0); + if ($name eq "mover.nfile") { + $units = pmiUnits(0,0,1,0,0,PM_COUNT_ONE); + } + elsif ($name eq "mover.nbyte") { + $type = PM_TYPE_U64; + } + elsif ($name eq "mover.max_file_size") { + $type = PM_TYPE_U64; + $sem = PM_SEM_INSTANT; + } + if (pmiAddMetric($name, PM_ID_NULL, $type, PM_INDOM_NULL, $sem, $units) < 0) { + pmiDump(); + die "pmiAddMetric($name, ...): " . pmiErrStr(-1) . "\n"; + } + $sts = pmiGetHandle($name, ""); + if ($sts < 0) { + pmiDump(); + die "pmiGetHandle($name, ...): " . pmiErrStr($sts) . "\n"; + } + push(@handle, $sts); +} + +# Handle metrics with multiple values, calling pmiAddMetric(). +# Defer to pmiGetHandle() to def_metric_inst(). +# +sub def_multi($$) +{ + my ($name,$indom) = @_; + my $type = PM_TYPE_U32; + my $sem = PM_SEM_COUNTER; + my $units = pmiUnits(0,0,1,0,0,PM_COUNT_ONE); + if (pmiAddMetric($name, PM_ID_NULL, $type, $indom, $sem, $units) < 0) { + pmiDump(); + die "pmiAddMetric($name, ...): " . pmiErrStr(-1) . "\n"; + } +} + +# Deal with metric-instance pairs. +# If first time this instance has been seen for this indom, add it to +# the instance domain. +# Get a handle and add it to handle[]. +# +sub def_metric_inst($$$) +{ + my ($name,$indom,$instance) = @_; + my $sts; + # inst_map{} holds the last allocated inst number with $indom as the + # key, and marks the instance as known with $indom . $instance as the + # key + if (!exists($inst_map{$indom . $instance})) { + my $inst; + if (exists($inst_map{$indom})) { + $inst_map{$indom}++; + $inst = $inst_map{$indom}; + } + else { + $inst_map{$indom} = 0; + $inst = 0; + } + if (pmiAddInstance($indom, $instance, $inst) < 0) { + pmiDump(); + die "pmiAddInstance([$name], $instance, $inst): " . pmiErrStr(-1) . "\n"; + } + $inst_map{$indom . $instance} = $inst; + } + $sts = pmiGetHandle($name, $instance); + if ($sts < 0) { + pmiDump(); + die "pmiGetHandle($name, $instance): " . pmiErrStr($sts) . "\n"; + } + push(@handle, $sts); +} + +# wrapper for pmiPutValueHandle(), using @handle +# +sub put($) +{ + my ($value) = @_; + my $sts; + if (!exists($handle[$h])) { + pmiDump(); + die <<EOF +put($value): No handle[] entry for index $h. +Check Handles in dump above. +EOF + } + $sts = pmiPutValueHandle($handle[$h], $value); + if ($sts < 0 && $putsts == 0) { $putsts = $sts }; + $h++; +} + +$sts = getopts('h:Z:', \%options); + +if (!defined($sts) || $#ARGV != 1) { + print "Usage: mover2pcp [-h host] [-Z timezone] infile outfile\n"; + exit(1); +} + +exists($options{h}) and $host = $options{t}; +if (exists($options{Z})) { + $zone = $options{Z}; + if ($zone !~ /^[-+][0-9][0-9][0-9][0-9]$/ && $zone ne "UTC") { + print "mover2pcp: Illegal -Z value, must be +NNNN or -NNNN or UTC\n"; + exit(1); + } +} + +pmiStart($ARGV[1], 0); +do_label(); + +open(INFILE, "<" . $ARGV[0]) + or die "mover2pcp: Failed to open infile \"$ARGV[0]\"\n"; + +# define metadata +def_single("mover.nfile"); +def_multi("mover.nfile_by_size", $sz_indom); +def_metric_inst("mover.nfile_by_size", $sz_indom, "<=1Kbyte"); +def_metric_inst("mover.nfile_by_size", $sz_indom, "<=1Mbyte"); +def_metric_inst("mover.nfile_by_size", $sz_indom, ">1Mbyte"); +def_single("mover.nbyte"); +def_single("mover.max_file_size"); + +while (<INFILE>) { + my @part; + chomp; + $line++; + print "[" . $line . "] $_\n"; + + # 2010-07-04 13:47:59 49 files (40, 9, 0) 118418 bytes (70669) + s/[(),]//g; # remove all (, ) and , + + @part = split(/\s+/, $_); + if ($#part != 9) { + print "[$line] $_\n"; + die "Number of values? expected 10, found " . ($#part+1) . "\n"; + } + + $nfile += $part[2]; + put($nfile); + $nfile_by_size[0] += $part[4]; + put($nfile_by_size[0]); + $nfile_by_size[1] += $part[5]; + put($nfile_by_size[1]); + $nfile_by_size[2] += $part[6]; + put($nfile_by_size[2]); + $nbyte += $part[7]; + put($nbyte); + put($part[9]); + + if ($putsts < 0) { + pmiDump(); + die "pmiPutValue: Failed @ $part[0] $part[1]: " . pmiErrStr($putsts) . "\n"; + } + if (pmiWrite(str2time($part[0] . "T" . $part[1], $zone), 0) < 0) { + pmiDump(); + die "pmiWrite: @ $part[0] $part[1]: " . pmiErrStr(-1) . "\n"; + } + $h = 0; + $putsts = 0; +} + +pmiEnd(); + +exit(0); + +=pod + +=head1 NAME + +mover2pcp - Import mover.log and create a PCP archive + +=head1 SYNOPSIS + +B<mover2pcp> [B<-Z> I<timezone>] I<infile> I<outfile> + +=head1 DESCRIPTION + +Add description here. + +=head1 SEE ALSO + +B<LOGIMPORT>(3), +B<PCP::LogImport>(3pm), +B<pmchart>(1), +B<pmie>(1) and +B<pmlogger>(1). diff --git a/man/html/importdata/moverv1 b/man/html/importdata/moverv1 new file mode 100755 index 0000000..431ffbe --- /dev/null +++ b/man/html/importdata/moverv1 @@ -0,0 +1,26 @@ +#!/usr/bin/perl +# +# Minimalist Version 1. +# + +use strict; +use warnings; +use Date::Parse; +use Date::Format; +use PCP::LogImport; + +pmiStart("mover_v1", 0); +pmiAddMetric("mover.nfile", + PM_ID_NULL, PM_TYPE_U32, PM_INDOM_NULL, + PM_SEM_INSTANT, pmiUnits(0,0,1,0,0,PM_COUNT_ONE)); + +open(INFILE, "<mover.log"); +while (<INFILE>) { + my @part; + chomp; + @part = split(/\s+/, $_); + pmiPutValue("mover.nfile", "", $part[2]); + pmiWrite(str2time($part[0] . "T" . $part[1], "UTC"), 0); +} + +pmiEnd(); diff --git a/man/html/importdata/moverv2 b/man/html/importdata/moverv2 new file mode 100755 index 0000000..4c376b8 --- /dev/null +++ b/man/html/importdata/moverv2 @@ -0,0 +1,29 @@ +#!/usr/bin/perl +# +# Minimalist Version 2. +# + +use strict; +use warnings; +use Date::Parse; +use Date::Format; +use PCP::LogImport; + +my $nfile = 0; + +pmiStart("mover_v2", 0); +pmiAddMetric("mover.nfile", + PM_ID_NULL, PM_TYPE_U32, PM_INDOM_NULL, + PM_SEM_COUNTER, pmiUnits(0,0,1,0,0,PM_COUNT_ONE)); + +open(INFILE, "<mover.log"); +while (<INFILE>) { + my @part; + chomp; + @part = split(/\s+/, $_); + $nfile += $part[2]; + pmiPutValue("mover.nfile", "", $nfile); + pmiWrite(str2time($part[0] . "T" . $part[1], "UTC"), 0); +} + +pmiEnd(); diff --git a/man/html/importdata/moverv3 b/man/html/importdata/moverv3 new file mode 100755 index 0000000..3899f75 --- /dev/null +++ b/man/html/importdata/moverv3 @@ -0,0 +1,40 @@ +#!/usr/bin/perl +# +# Minimalist Version 3. +# + +use strict; +use warnings; +use Date::Parse; +use Date::Format; +use PCP::LogImport; + +my $nfile = 0; +my $nbyte = 0; + +pmiStart("mover_v3", 0); +pmiAddMetric("mover.nfile", + PM_ID_NULL, PM_TYPE_U32, PM_INDOM_NULL, + PM_SEM_COUNTER, pmiUnits(0,0,1,0,0,PM_COUNT_ONE)); +pmiAddMetric("mover.nbyte", + PM_ID_NULL, PM_TYPE_U64, PM_INDOM_NULL, + PM_SEM_COUNTER, pmiUnits(1,0,0,PM_SPACE_BYTE,0,0)); +pmiAddMetric("mover.max_file_size", + PM_ID_NULL, PM_TYPE_U64, PM_INDOM_NULL, + PM_SEM_INSTANT, pmiUnits(1,0,0,PM_SPACE_BYTE,0,0)); + +open(INFILE, "<mover.log"); +while (<INFILE>) { + my @part; + chomp; + s/[(),]//g; # all remove (, ) and , + @part = split(/\s+/, $_); + $nfile += $part[2]; + pmiPutValue("mover.nfile", "", $nfile); + $nbyte += $part[7]; + pmiPutValue("mover.nbyte", "", $nbyte); + pmiPutValue("mover.max_file_size", "", $part[9]); + pmiWrite(str2time($part[0] . "T" . $part[1], "UTC"), 0); +} + +pmiEnd(); diff --git a/man/html/importdata/moverv4 b/man/html/importdata/moverv4 new file mode 100755 index 0000000..a84d085 --- /dev/null +++ b/man/html/importdata/moverv4 @@ -0,0 +1,54 @@ +#!/usr/bin/perl +# +# Minimalist Version 4. +# + +use strict; +use warnings; +use Date::Parse; +use Date::Format; +use PCP::LogImport; + +my $nfile = 0; +my $nbyte = 0; +my $sz_indom = pmInDom_build(PMI_DOMAIN, 0); +my @nfile_by_size = (0,0,0); + +pmiStart("mover_v4", 0); +pmiAddMetric("mover.nfile", + PM_ID_NULL, PM_TYPE_U32, PM_INDOM_NULL, + PM_SEM_COUNTER, pmiUnits(0,0,1,0,0,PM_COUNT_ONE)); +pmiAddMetric("mover.nfile_by_size", + PM_ID_NULL, PM_TYPE_U32, $sz_indom, + PM_SEM_COUNTER, pmiUnits(0,0,1,0,0,PM_COUNT_ONE)); +pmiAddInstance($sz_indom, "<=1Kbyte", 0); +pmiAddInstance($sz_indom, "<=1Mbyte", 1); +pmiAddInstance($sz_indom, ">1Mbyte", 2); +pmiAddMetric("mover.nbyte", + PM_ID_NULL, PM_TYPE_U64, PM_INDOM_NULL, + PM_SEM_COUNTER, pmiUnits(1,0,0,PM_SPACE_BYTE,0,0)); +pmiAddMetric("mover.max_file_size", + PM_ID_NULL, PM_TYPE_U64, PM_INDOM_NULL, + PM_SEM_INSTANT, pmiUnits(1,0,0,PM_SPACE_BYTE,0,0)); + +open(INFILE, "<mover.log"); +while (<INFILE>) { + my @part; + chomp; + s/[(),]//g; # all remove (, ) and , + @part = split(/\s+/, $_); + $nfile += $part[2]; + pmiPutValue("mover.nfile", "", $nfile); + $nfile_by_size[0] += $part[4]; + pmiPutValue("mover.nfile_by_size", "<=1Kbyte", $nfile_by_size[0]); + $nfile_by_size[1] += $part[5]; + pmiPutValue("mover.nfile_by_size", "<=1Mbyte", $nfile_by_size[1]); + $nfile_by_size[2] += $part[6]; + pmiPutValue("mover.nfile_by_size", ">1Mbyte", $nfile_by_size[2]); + $nbyte += $part[7]; + pmiPutValue("mover.nbyte", "", $nbyte); + pmiPutValue("mover.max_file_size", "", $part[9]); + pmiWrite(str2time($part[0] . "T" . $part[1], "UTC"), 0); +} + +pmiEnd(); diff --git a/man/html/index.html b/man/html/index.html new file mode 100644 index 0000000..d8ae702 --- /dev/null +++ b/man/html/index.html @@ -0,0 +1,91 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> +<HTML> +<HEAD> + <meta http-equiv="content-type" content="text/html; charset=utf-8"> + <meta http-equiv="content-style-type" content="text/css"> + <link href="pcpdoc.css" rel="stylesheet" type="text/css"> + <link href="images/pcp.ico" rel="icon" type="image/ico"> + <TITLE>PCP Manual</TITLE> +</HEAD> +<BODY LANG="en-AU" TEXT="#000060" DIR="LTR"> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 STYLE="page-break-before: always"> + <TR> <TD WIDTH=64 HEIGHT=64><A HREF="http://pcp.io/"><IMG SRC="images/pcpicon.png" NAME="pcpicon" ALIGN=TOP WIDTH=64 HEIGHT=64 BORDER=0></A></TD> + <TD WIDTH=1><P> </P></TD> + <TD WIDTH=500><P VALIGN=MIDDLE ALIGN=LEFT><A HREF="index.html"><FONT COLOR="#cc0000">Home</FONT></A> · <A HREF="lab.pmchart.html"><FONT COLOR="#cc0000">Charts</FONT></A> · <A HREF="timecontrol.html"><FONT COLOR="#cc0000">Time Control</FONT></A></P></TD> + </TR> +</TABLE> +<H1 ALIGN=CENTER STYLE="margin-top: 0.48cm; margin-bottom: 0.32cm"><FONT SIZE=7>PCP Manual</FONT></H1> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 BGCOLOR="#e2e2e2"> + <TR><TD WIDTH=100% BGCOLOR="#081c59"><P ALIGN=LEFT><FONT SIZE=5 COLOR="#ffffff"><B><A NAME="starting">Getting Started</A></B></FONT></P></TD></TR> +</TABLE> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=10 BGCOLOR="#e2e2e2"> + <TR><TD WIDTH=50%><UL> + <LI><A HREF="pcpintro.html"><FONT COLOR="#000060">Introduction to PCP</FONT></A> + <LI><A HREF="installation.html"><FONT COLOR="#000060">Installation</FONT></A> + <LI><A HREF="guide.redhat.html"><FONT COLOR="#000060">Quick Reference Guide (Red Hat)</FONT></A> + </UL></TD> + <TD WIDTH=50%><UL> + <LI><A HREF="overview.html"><FONT COLOR="#000060">Charts Overview</FONT></A> + <LI><A HREF="timecontrol.html"><FONT COLOR="#000060">Time Control Overview</FONT></A> + </UL></TD></TR> +</TABLE> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 BGCOLOR="#e2e2e2"> + <TR><TD WIDTH=100% BGCOLOR="#081c59"><P ALIGN=LEFT><FONT SIZE=5 COLOR="#ffffff"><B><A NAME="tutorials">Tutorials</A></B></FONT></P></TD></TR> +</TABLE> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=10 BGCOLOR="#e2e2e2"> + <TR> <TD WIDTH=50%><UL> + <LI><A HREF="lab.pmchart.html"><FONT COLOR="#000060">Using Charts</FONT></A> + <LI><A HREF="lab.pmlogger.html"><FONT COLOR="#000060">Logging Basics</FONT></A> + <LI><A HREF="#lab.pmlogconf.html"><FONT COLOR="#ffffff">Configuring Logging</FONT></A> + <LI><A HREF="lab.pmie.html"><FONT COLOR="#000060">Automated Reasoning Basics</FONT></A> + <LI><A HREF="lab.pmieconf.html"><FONT COLOR="#000060">Configuring Automated Reasoning</FONT></A> + <LI><A HREF="lab.secure.html"><FONT COLOR="#000060">Secure Connections</FONT></A> + </UL></TD> + <TD WIDTH=50%><UL> + <LI><A HREF="lab.auth.html"><FONT COLOR="#000060">Authenticated Connections</FONT></A> + <LI><A HREF="#lab.pmdas.html"><FONT COLOR="#ffffff">Adding metrics <I>(C, Perl, Python)</I></FONT></A> + <LI><A HREF="#lab.mmapvalues.html"><FONT COLOR="#ffffff">Adding metrics using the MMV agent <I>(C, Perl, Java)</I></FONT></A> + <LI><A HREF="lab.trace.html"><FONT COLOR="#000060">Adding metrics using the trace agent</FONT></A> <I>(C, sh)</I> + <LI><A HREF="lab.importdata.html"><FONT COLOR="#000060">Importing data and creating PCP archives <I>(C, Perl)</I></FONT></A> + <LI><A HREF="lab.pmview.html"><FONT COLOR="#000060">Using 3D Views <I>(experimental)</I></FONT></A> + </UL></TD></TR> +</TABLE> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 BGCOLOR="#e2e2e2"> + <TR><TD WIDTH=100% BGCOLOR="#081c59"><P ALIGN=LEFT><FONT SIZE=5 COLOR="#ffffff"><B><A NAME="casestudies">Case Studies</A></B></FONT></P></TD></TR> +</TABLE> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=10 BGCOLOR="#e2e2e2"> + <TR><TD WIDTH=50%><UL> + <LI><A HREF="howto.cpuperf.html"><FONT COLOR="#000060">Analysing processor utilisation</FONT></A> + <LI><A HREF="howto.diskperf.html"><FONT COLOR="#000060">Analysing storage performance</FONT></A> + <LI><A HREF="howto.systemlog.html"><FONT COLOR="#000060">System Event Log Instrumentation</FONT></A> + </UL></TD> + <TD WIDTH=50%><UL> + <LI><A HREF="howto.diskmodel.html"><FONT COLOR="#000060">Comparing storage performance</FONT></A> + <LI><A HREF="howto.enterprise.html"><FONT COLOR="#000060">Management framework integration</FONT></A> + </UL></TD> </TR> +</TABLE> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 BGCOLOR="#e2e2e2"> + <TR><TD WIDTH=100% BGCOLOR="#081c59"><P ALIGN=LEFT><FONT SIZE=5 COLOR="#ffffff"><B>Footnotes</B></FONT></P></TD></TR> +</TABLE> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=10 BGCOLOR="#e2e2e2"> + <TR><TD WIDTH=50%><UL> + <LI><A HREF="glossary.html"><FONT COLOR="#000060">Glossary</FONT></A> + <LI><A HREF="contacts.html"><FONT COLOR="#000060">Contacts</FONT></A> + <LI><A HREF="credits.html"><FONT COLOR="#000060">Credits</FONT></A> + </UL></TD> + <TD WIDTH=50%><UL> + <LI><A HREF="gpl.html"><FONT COLOR="#000060">GNU GPL</FONT></A> + <LI><A HREF="qwtlicense.html"><FONT COLOR="#000060">QWT License</FONT></A> + <LI><A HREF="cclicense.html"><FONT COLOR="#000060">Creative Commons License</FONT></A> + <BR> + </UL></TD></TR> +</TABLE> +<HR> +<CENTER> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0> + <TR> <TD WIDTH=50%><P>Copyright © 2007-2010 <A HREF="http://www.aconex.com/"><FONT COLOR="#000060">Aconex</FONT></A><BR>Copyright © 2000-2004 <A HREF="http://www.sgi.com/"><FONT COLOR="#000060">Silicon Graphics Inc</FONT></P></TD> + <TD WIDTH=50%><P ALIGN=RIGHT><A HREF="http://pcp.io/"><FONT COLOR="#000060">PCP Site</FONT></A><BR>Copyright © 2012-2014 <A HREF="http://www.redhat.com/"><FONT COLOR="#000060">Red Hat</FONT></P></TD> </TR> +</TABLE> +</CENTER> +</BODY> +</HTML> diff --git a/man/html/installation.html b/man/html/installation.html new file mode 100644 index 0000000..f5a077c --- /dev/null +++ b/man/html/installation.html @@ -0,0 +1,143 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> +<HTML> +<HEAD> + <meta http-equiv="content-type" content="text/html; charset=utf-8"> + <meta http-equiv="content-style-type" content="text/css"> + <link href="pcpdoc.css" rel="stylesheet" type="text/css"> + <link href="images/pcp.ico" rel="icon" type="image/ico"> + <TITLE>PCP Installation</TITLE> +</HEAD> +<BODY LANG="en-AU" TEXT="#000060" DIR="LTR"> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 STYLE="page-break-before: always"> + <TR> <TD WIDTH=64 HEIGHT=64><A HREF="http://pcp.io/"><IMG SRC="images/pcpicon.png" NAME="pcpicon" ALIGN=TOP WIDTH=64 HEIGHT=64 BORDER=0></A></TD> + <TD WIDTH=1><P> </P></TD> + <TD WIDTH=500><P VALIGN=MIDDLE ALIGN=LEFT><A HREF="index.html"><FONT COLOR="#cc0000">Home</FONT></A> · <A HREF="lab.pmchart.html"><FONT COLOR="#cc0000">Charts</FONT></A> · <A HREF="timecontrol.html"><FONT COLOR="#cc0000">Time Control</FONT></A></P></TD> + </TR> +</TABLE> +<H1 ALIGN=CENTER STYLE="margin-top: 0.48cm; margin-bottom: 0.32cm"><FONT SIZE=7>Installation</FONT></H1> +<P>Binary packages for Linux (<i>deb</i> and <i>rpm</i> formats), Mac OS X, Solaris and Windows are made available by the PCP development team. The latest version can always be found in the download section of the <A HREF="http://pcp.io/">PCP project</A> web pages. Its also worth noting that many Linux distributions now ship PCP - these include Debian, Fedora, Slackware, SuSE and Ubuntu.</P> +<P>PCP GUI runs natively on Mac OS X, X11 (Linux/Unix) and Windows, and binary packages for these platforms are available in the same location. The installation instructions for each differ significantly - below we discuss each in turn, and finally cover building the tools from source.</P> +<UL> + <LI><A HREF="#rpm">Linux (rpm format)</A> + <LI><A HREF="#deb">Linux (deb format)</A> + <LI><A HREF="#mac">Mac OS X</A> + <LI><A HREF="#sun">Solaris</A> + <LI><A HREF="#win">Windows</A> + <LI><A HREF="#src">Building from source</A> +</UL> +<P>The typical PCP installation is conceptually divided into two major components - <A HREF="glossary.html#collector">collectors</A> and <A HREF="glossary.html#monitor">monitors</A>. There are usually multiple systems of each type in any given deployment.</P> +<P>For server-focussed systems (Linux in particular) PCP is literally divided into multiple packages along these lines, with separate PCP and PCP GUI packages (primarily due to dependencies on graphical libraries which are unlikely to be installed on a Linux server). On the other platforms, like Mac OS X and Windows, this is less of an issue and so a single PCP package is shipped which covers both needs.</P> +<P>PCP GUI has a runtime dependency on the Qt4 shared libraries. These are usually available from a package named <B>qt4</B>. Versions before Qt4.4 of the Qt libraries <I><B>will not work</B></I>.</P> + +<P><BR></P> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 BGCOLOR="#e2e2e2"> + <TR><TD WIDTH=100% BGCOLOR="#081c59"><P ALIGN=LEFT><FONT SIZE=5 COLOR="#ffffff"><B>Linux using <A NAME="rpm"><I>rpm</I></A> format (Fedora, RHEL, SuSE)</B></FONT></P></TD></TR> +</TABLE> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=10 CELLSPACING=20> + <TR><TD BGCOLOR="#e2e2e2" WIDTH=70%><BR><IMG SRC="images/stepfwd_on.png" WIDTH=16 HEIGHT=16 BORDER=0> If using packages <B>from your distribution</B>, in a command shell enter:<BR> +<PRE><B> +# yum install pcp pcp-gui +</B></PRE> +<BR> + If using packages <B>downloaded from ftp.pcp.io</B>, in a command shell enter:<BR> +<PRE><B> +# rpm -Uvh *pcp*.rpm +</B></PRE> +<BR> +</TD></TR> +</TABLE> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 BGCOLOR="#e2e2e2"> + <TR><TD WIDTH=100% BGCOLOR="#081c59"><P ALIGN=LEFT><FONT SIZE=5 COLOR="#ffffff"><B>Linux using <A NAME="deb"><I>deb</I></A> format (Debian, Ubuntu)</B></FONT></P></TD></TR> +</TABLE> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=10 CELLSPACING=20> + <TR><TD BGCOLOR="#e2e2e2" WIDTH=70%><BR><IMG SRC="images/stepfwd_on.png" WIDTH=16 HEIGHT=16 BORDER=0> If using packages <B>from your distribution</B>, in a command shell enter:<BR> +<PRE><B> +# apt-get install pcp pcp-gui +</B></PRE> +<BR> + If using packages <B>downloaded from ftp.pcp.io</B>, in a command shell enter:<BR> +<PRE><B> +# dpkg -i *pcp*.deb +</B></PRE> +<BR> +</TD></TR> +</TABLE> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 BGCOLOR="#e2e2e2"> + <TR><TD WIDTH=100% BGCOLOR="#081c59"><P ALIGN=LEFT><FONT SIZE=5 COLOR="#ffffff"><B><A NAME="mac">Mac</A> OS X Installation</B></FONT></P></TD></TR> +</TABLE> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=10 CELLSPACING=20> + <TR><TD BGCOLOR="#e2e2e2" WIDTH=70%><BR><IMG SRC="images/stepfwd_on.png" WIDTH=16 HEIGHT=16 BORDER=0> After downloading the <I>dmg</I> file for your platform, double-click on the PCP <I>dmg</I> icon, and follow the installation instructions presented by the Installer.<BR> +<BR> +</TD></TR> +</TABLE> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 BGCOLOR="#e2e2e2"> + <TR><TD WIDTH=100% BGCOLOR="#081c59"><P ALIGN=LEFT><FONT SIZE=5 COLOR="#ffffff"><B><A NAME="sun">Solaris</A> Installation</B></FONT></P></TD></TR> +</TABLE> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=10 CELLSPACING=20> + <TR><TD BGCOLOR="#e2e2e2" WIDTH=70%><BR><IMG SRC="images/stepfwd_on.png" WIDTH=16 HEIGHT=16 BORDER=0> After downloading (and gunzip'ing) the binary package, to perform a fresh install:<BR> +<PRE><B> +# pkgadd -d pcp-X.Y.Z +<I> Say 'y' to all the questions</I> +# svcadm enable pmcd +</B></PRE><BR> +Or to update to a newer version: +<PRE><B> +# pkgrm pcp-X.Y.OLD +# pkgadd -d pcp X.Y.Z +# svcadm enable pmcd +</B></PRE> +<BR> +</TD></TR> +</TABLE> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 BGCOLOR="#e2e2e2"> + <TR><TD WIDTH=100% BGCOLOR="#081c59"><P ALIGN=LEFT><FONT SIZE=5 COLOR="#ffffff"><B><A NAME="win">Windows</A> Installation</B></FONT></P></TD></TR> +</TABLE> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=10 CELLSPACING=20> + <TR><TD BGCOLOR="#e2e2e2" WIDTH=70%><BR><IMG SRC="images/stepfwd_on.png" WIDTH=16 HEIGHT=16 BORDER=0> After downloading the PCP Glider <I>msi</I> file, right-click on the command prompt icon, select <I><B>Run As Administrator</B></I>, and enter:<BR> +<PRE><B> +# msiexec /i pcp-glider-*.msi +# cd C:\Glider\scripts +# postinst.bat +</B></PRE><BR> +Before upgrading or removing PCP Glider, run: +<PRE><B> +# cd C:\Glider\scripts +# prerm.bat +</B></PRE><BR> +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 <I>Start</I> menu. +<BR> +</TD></TR> +</TABLE> + +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 BGCOLOR="#e2e2e2"> + <TR><TD WIDTH=100% BGCOLOR="#081c59"><P ALIGN=LEFT><FONT SIZE=5 COLOR="#ffffff"><B>Building from <A NAME="src">source</A></B></FONT></P></TD></TR> +</TABLE> +<P>The best way to build PCP is to use the <B>git</B> source code management (SCM) tools. This SCM is freely available and runs natively on many different platforms. +<TABLE WIDTH=100% BORDER=0 CELLPADDING=10 CELLSPACING=20> + <TR><TD BGCOLOR="#e2e2e2" WIDTH=70%><BR><IMG SRC="images/stepfwd_on.png" WIDTH=16 HEIGHT=16 BORDER=0> First, get the current version of the source code:<BR> +<PRE><B> +$ git clone git://git.pcp.io/pcp +</B></PRE><BR> +Then build and install: +<PRE><B> +$ cd pcp +$ ./configure --prefix=/usr --sysconfdir=/etc --localstatedir=/var +$ make +# make install +</B></PRE> +<BR> +</TD></TR> +</TABLE> +<P>When building from source, you'll need to ensure you have the following tools and libraries installed: a C compiler (for core PCP), a C++ compiler (for PCP GUI), <I>autoconf</I>, <I>lex</I>, <I>yacc</I>, and the Qt4 development tools (including <I>qmake</I>), libraries and headers. On Mac OS X, the Apple <I>Xcode</I> development environment is also required, as it is used by the Qt application build process. <I>Inkscape</I> - a Scalable Vector Graphics (SVG) editor - can be used to modify the icons, but is not required during the build process.</P> +<P>If you encounter difficulties building PCP, consult the <A HREF="contacts.html">contacts page</A> which contains contact information for people who can provide additional assistance.</P> + +<P><BR></P> +<HR> +<CENTER> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0> + <TR> <TD WIDTH=50%><P>Copyright © 2007-2010 <A HREF="http://www.aconex.com/"><FONT COLOR="#000060">Aconex</FONT></A><BR>Copyright © 2000-2004 <A HREF="http://www.sgi.com/"><FONT COLOR="#000060">Silicon Graphics Inc</FONT></P></TD> + <TD WIDTH=50%><P ALIGN=RIGHT><A HREF="http://pcp.io/"><FONT COLOR="#000060">PCP Site</FONT></A><BR>Copyright © 2012-2014 <A HREF="http://www.redhat.com/"><FONT COLOR="#000060">Red Hat</FONT></P></TD> </TR> +</TABLE> +</CENTER> +</BODY> +</HTML> diff --git a/man/html/lab.auth.html b/man/html/lab.auth.html new file mode 100644 index 0000000..26c6ddf --- /dev/null +++ b/man/html/lab.auth.html @@ -0,0 +1,427 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN"> +<!-- + (c) Copyright 2013 Red Hat. + 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 + http://creativecommons.org/licenses/by-sa/3.0/us/ . +--> +<HTML> +<HEAD> + <meta http-equiv="content-type" content="text/html; charset=utf-8"> + <meta http-equiv="content-style-type" content="text/css"> + <link href="pcpdoc.css" rel="stylesheet" type="text/css"> + <link href="images/pcp.ico" rel="icon" type="image/ico"> + <TITLE>Authenticated Connections</TITLE> +</HEAD> +<BODY LANG="en-AU" TEXT="#000060" DIR="LTR"> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 STYLE="page-break-before: always"> + <TR> <TD WIDTH=64 HEIGHT=64><FONT COLOR="#000080"><A HREF="http://pcp.io/"><IMG SRC="images/pcpicon.png" NAME="pmcharticon" ALIGN=TOP WIDTH=64 HEIGHT=64 BORDER=0></A></FONT></TD> + <TD WIDTH=1><P> </P></TD> + <TD WIDTH=500><P VALIGN=MIDDLE ALIGN=LEFT><A HREF="index.html"><FONT COLOR="#cc0000">Home</FONT></A> · <A HREF="lab.pmchart.html"><FONT COLOR="#cc0000">Charts</FONT></A> · <A HREF="timecontrol.html"><FONT COLOR="#cc0000">Time Control</FONT></A></P></TD> + </TR> +</TABLE> +<H1 ALIGN=CENTER STYLE="margin-top: 0.48cm; margin-bottom: 0.32cm"><FONT SIZE=7>Authenticated Connections</FONT></H1> +<TABLE WIDTH=15% BORDER=0 CELLPADDING=5 CELLSPACING=10 ALIGN=RIGHT> + <TR><TD BGCOLOR="#e2e2e2"><IMG SRC="images/system-search.png" WIDTH=16 HEIGHT=16 BORDER=0> <I>Tools</I><BR><PRE> +pmcd +pminfo +pmchart +pmconfig +pmdaproc +pluginviewer +saslauthd +saslpasswd2 +sasldblistusers2 +kadmin.local +kinit +klist +</PRE></TD></TR> +</TABLE> +<P>This chapter of the Performance Co-Pilot tutorial covers setting up authenticated +connections between PCP collector and monitor components. +An authenticated connection is one where the PCP collector (<B>pmcd</B> and PMDAs) +is made aware of the credentials of the user running the monitor tools. +This allows the PCP collector software to perform two important functions: +<OL> + <LI> Grant additional access, allowing potentially sensitive information to be + accessed by the authenticated user; + <LI> Make access control decisions for users and groups in order to prevent + inappropriate access to metrics or over-subscription of server resources. +</OL> +<P>For an explanation of Performance Co-Pilot terms and acronyms, consult +the <A HREF="glossary.html">PCP glossary</A>.</P> +<UL> + <LI> <A HREF="#overview">Overview</A> + <LI> <A HREF="#unix">Local Credentials</A> + <LI> <A HREF="#sasl">Remote Access</A> + <UL> + <LI> <A HREF="#sasldb">Using sasldb</A> + <LI> <A HREF="#saslauthd">Using saslauthd</A> + <LI> <A HREF="#gssapi">Kerberos (GSSAPI)</A> + </UL> +</UL> +<P>Note: remote host authentication will often warrant the configuration of secure +connections between PCP monitors and collectors - this is covered by a separate +tutorial: <A HREF="lab.secure.html">Secure Connections</A>.</P> + +<P><BR></P> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 BGCOLOR="#e2e2e2"> + <TR><TD WIDTH=100% BGCOLOR="#081c59"><P ALIGN=LEFT><FONT SIZE=5 COLOR="#ffffff"><B><A NAME="overview">Overview</I></A></B></FONT></P></TD></TR> +</TABLE> +<P>All connections made to the PCP metrics collector daemon (<B>pmcd</B>) +are made using the PCP protocol, which is TCP/IP based. Traditionally, no +functionality was available to identify the user making a connection between +a PCP monitor and collector. However, as PCP evolved to be able to export +sensitive information (event trace parameters and detailed per-process +statistics, for example), it became necessary to provide such mechanisms.</P> + +<P>The Performance Co-Pilot has two facilities for transfering credentials +between the monitoring and collecting components - a local-host-only facility +using Unix domain sockets, and SASL-based authentication which can be over +either IPv4 or IPv6 sockets (local or remote).</P> + +<P><BR></P> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 BGCOLOR="#e2e2e2"> + <TR><TD WIDTH=100% BGCOLOR="#081c59"><P ALIGN=LEFT><FONT SIZE=5 COLOR="#ffffff"><B><A NAME="unix">Local Credentials</A></B></FONT></P></TD></TR> +</TABLE> + +<P>For local connections, there is a fast local transport mechanism +using Unix domain sockets. These sockets provide a facility whereby the +userid and groupid of the monitor process is automatically made available +to the collector process, with no user intervention being required.</P> + +<P>This will become the default localhost transport mechanism over time. +However, its use can be requested via the <I>unix:</I> host specification +(<B>-h</B> option) with all monitor tools.</P> + +<P>In the following exercise, we make use of per-process metrics from the +<B>pmdaproc</B> PCP Collector agent. +This PMDA is enabled by default, and makes use of authenticated credentials +from the monitor tools to gate access to sensitive information - process +identifiers, names, arguments, and so forth. +In modern versions of PCP, this information is unavailable (PM_ERR_PERMISSION +is returned) unless the PMDA has been given user credentials.</P> + +<TABLE WIDTH=100% BORDER=0 CELLPADDING=10 CELLSPACING=20> + <TR><TD BGCOLOR="#e2e2e2" WIDTH=70%><BR><IMG SRC="images/stepfwd_on.png" WIDTH=16 HEIGHT=16 BORDER=0> Check for support, then establish a Unix domain socket connection with automatic credentials transfer:<BR> +<PRE><B> +$ pmconfig -L | grep ^unix +unix_domain_sockets=true + +$ pmprobe -f -h localhost proc.fd.count +proc.fd.count -12387 No permission to perform requested operation + +$ pmprobe -f -h unix: proc.fd.count +proc.fd.count 118 + +$ pminfo -dmt -h unix: proc.fd.count + +proc.fd.count PMID: 3.51.0 [open file descriptors] + Data Type: 32-bit unsigned int InDom: 3.9 0xc00009 + Semantics: instant Units: count +</B></PRE> +</TD></TR> +</TABLE> + +<P>A <I>local:</I> specification is also available, which indicates that +the monitor tool should first attempt to establish a Unix domain socket +connection (with automatic credentials transfer), but failing that fall back +to the traditional socket connection style (with no credentials transfer, +unless mandated by collector or explicitly requested by the monitor user - +described later in this tutorial).</P> + +<P><B>Note:</B> this facility is completely independent and separate +to the remote access facility (described later). +Therefore, it can still be used even when support for the remote +authentication facilities is unavailable or not configured. +This local facility is always enabled on platforms that support it - these +include Linux, Mac OS X and Solaris. +</P> + +<P><BR></P> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 BGCOLOR="#e2e2e2"> + <TR><TD WIDTH=100% BGCOLOR="#081c59"><P ALIGN=LEFT><FONT SIZE=5 COLOR="#ffffff"><B><A NAME="sasl">Remote Access</A></B></FONT></P></TD></TR> +</TABLE> + +<P>The alternative authentication facility is the "Simple Authentication and +Security Layer" (SASL) which provides for remote authentication. +Usually this would be used with a <A HREF="lab.secure.html">secure connection</A> +to ensure sensitive information is not transmitted in the clear.</P> + +<P>SASL can be configured with many different authentication mechanisms, and this +configuration is done transparently (outside of PCP, as described shortly). +This list of mechanisms can be changed via the <I>mech_list</I> entry in the +<I>/etc/sasl2/pmcd.conf</I> file, along with other critical security parameters +defining how <B>pmcd</B> should handle authentication requests. + +The <I>mech_list</I> can be set to any one of the installed SASL mechanisms, +or a space-separated list of mechanisms from which the monitor tools can select. +There are also situations where it makes sense to not set <I>mech_list</I> at +all, which we will explore shortly.</P> + +<P>To make use of SASL-based authentication, both monitor and collector systems +need to be capable of running the SASL code (PCP support, in particular, must +be present on each end of the connection). +As demonstrated in the following examples, we can use both the <B>pmconfig</B> +PCP command and the <B>pluginviewer</B> SASL command to interogate aspects of +the installations on each end of a connection. +The <B>pluginviewer</B> command has separate options for reporting on client +(<B>-c</B>) and server (<B>-s</B>) components of an installation. +</P> + +<I><B><A NAME="sasldb">Using sasldb</A></B></I> +<P>The SASL library provides a custom authentication technique, independent +to the set of users and groups on a system, called <I>sasldb</I>. +This involves the creation of a new authentication database separate to the +native login mechanisms that a host provides. One advantage of using it is +that it does not require any special privileges on the part of the daemon +performing authentication (<B>pmcd</B> in our case - which does not run as +a privileged process and thus typically cannot be used with the common +authentication databases, such as the <I>/etc/shadow</I> mechanism).</P> + +<P>The <I>sasldb</I> approach can be used with several SASL mechanisms, and +it is commonly used to verify a SASL setup. Here, we will configure PCP to +use <I>sasldb</I> by allowing the "plain" SASL mechanism to +authenticate against it.</P> + +<TABLE WIDTH=100% BORDER=0 CELLPADDING=10 CELLSPACING=20> + <TR><TD BGCOLOR="#e2e2e2" WIDTH=70%><BR><IMG SRC="images/stepfwd_on.png" WIDTH=16 HEIGHT=16 BORDER=0> Check for support:<BR> +<PRE><B> +$ pmconfig -L | egrep '^auth|^secure' +secure_sockets=true +authentication=true + +$ pluginviewer -s -m PLAIN +[...] +Plugin "plain" [loaded], API version: 4 + SASL mechanism: PLAIN, best SSF: 0, supports setpass: no + security flags: NO_ANONYMOUS|PASS_CREDENTIALS + features: WANT_CLIENT_FIRST|PROXY_AUTHENTICATION +</B></PRE> +</TD></TR> +</TABLE> + +<P>Modify the <I>/etc/sasl2/pmcd.conf</I> configuration file, so that it makes +"plain" authentication available to PCP monitor tools, and also +to specify the location of the SASL credentials database file.</P> + +<P>By default, this has been specified as <I>/etc/pcp/passwd.db</I>. +SASL commands allow this database to be manipulated - adding, listing and +deleting users, setting their passwords, and so on.</P> + +<TABLE WIDTH=100% BORDER=0 CELLPADDING=10 CELLSPACING=20> + <TR><TD BGCOLOR="#e2e2e2" WIDTH=70%><BR><IMG SRC="images/stepfwd_on.png" WIDTH=16 HEIGHT=16 BORDER=0> Configure the SASL library:<BR> +<PRE><B> +# grep PCP_SASLCONF_DIR /etc/pcp.conf +PCP_SASLCONF_DIR=/etc/sasl2 + +# cat $PCP_SASLCONF_DIR/sasl2/pmcd.conf +mech_list: plain digest-md5 gssapi +sasldb_path: /etc/pcp/passwd.db +</B></PRE> +</TD></TR> +</TABLE> + +<P>Next we create the database and add some users to it. +Note that requires the previous step to have been performed, +as that informs the tools about the location of the database.</P> + +<TABLE WIDTH=100% BORDER=0 CELLPADDING=10 CELLSPACING=20> + <TR><TD BGCOLOR="#e2e2e2" WIDTH=70%><BR><IMG SRC="images/stepfwd_on.png" WIDTH=16 HEIGHT=16 BORDER=0> Administer the SASL database (add, list and disable users):<BR> +<PRE><B> +# saslpasswd2 -a pmcd jack +Password: xxxxxx +Again (for verification): xxxxxx + +# saslpasswd2 -a pmcd jill +Password: xxxxxx +Again (for verification): xxxxxx + +# sasldblistusers2 -f /etc/pcp/passwd.db +jack@server.demo.net: userPassword +jill@server.demo.net: userPassword + +# saslpasswd2 -a pmcd -d jill + +# $PCP_RC_DIR/pmcd restart +</B></PRE> +</TD></TR> +</TABLE> + +<P>Finally, we're ready to try it out. As we have just restarted <B>pmcd</B> +(above), its worth checking its log file - <I>$PCP_LOG_DIR/pmcd/pmcd.log</I> - +and if that is free of errors, we can attempt to authenticate.</P> + +<TABLE WIDTH=100% BORDER=0 CELLPADDING=10 CELLSPACING=20> + <TR><TD BGCOLOR="#e2e2e2" WIDTH=70%><BR><IMG SRC="images/stepfwd_on.png" WIDTH=16 HEIGHT=16 BORDER=0> Establish an authenticated connection:<BR> +<PRE><B> +$ pminfo -fmdt -h pcps://server.demo.net?method=plain proc.fd.count +Username: jack +Password: xxxxxx + +proc.fd.count PMID: 3.51.0 [open file descriptors] + Data Type: 32-bit unsigned int InDom: 3.9 0xc00009 + Semantics: instant Units: count + inst [1281 or "001281 bash"] value 4 + inst [1287 or "001287 make -j 8 default_pcp"] value 5 + inst [1802 or "001802 bash"] value 4 + [...] +</B></PRE> +</TD></TR> +</TABLE> + +<I><B><A NAME="saslauthd">Using saslauthd</A></B></I> +<P>The SASL mechanism configured by default on a PCP collector system is <I>sasldb</I> +which provides a basic username and password style authentication mechanism with no +reliance on external daemons, package dependencies, and so on. +Without customisation for individual users, as described above, it allows no access +and can thus be considered secure-by-default.</P> + +<P>However, it is often more convenient to use the same authentication mechanism +that is used when logging in to a host (e.g. PAM on Linux and Solaris). +Because the PCP daemons run without superuser privileges, they cannot perform this +authentication themselves, and so it must be achieved using a separate, privileged +process. +SASL provides <I>saslauthd</I> for this purpose.</P> + +<TABLE WIDTH=100% BORDER=0 CELLPADDING=10 CELLSPACING=20> + <TR><TD BGCOLOR="#e2e2e2" WIDTH=70%><BR><IMG SRC="images/stepfwd_on.png" WIDTH=16 HEIGHT=16 BORDER=0> Check for support:<BR> +<PRE><B> +$ pmconfig -L | egrep '^auth|^secure' +secure_sockets=true +authentication=true + +$ pluginviewer -s -m PLAIN +[...] +Plugin "plain" [loaded], API version: 4 + SASL mechanism: PLAIN, best SSF: 0, supports setpass: no + security flags: NO_ANONYMOUS|PASS_CREDENTIALS + features: WANT_CLIENT_FIRST|PROXY_AUTHENTICATION + +$ ps ax | grep saslauthd + 2857 ? Ss 0:00 /usr/sbin/saslauthd -m /var/run/saslauthd -a pam + 2858 ? S 0:00 /usr/sbin/saslauthd -m /var/run/saslauthd -a pam +[...] +</B></PRE> +</TD></TR> +</TABLE> + +<P>In this case, the SASL mechanism configuration is entirely handled by +<I>saslauthd</I> so we simply need to ensure we pass authentication +through to the daemon - no configuration beyond that should be needed.</P> + +<TABLE WIDTH=100% BORDER=0 CELLPADDING=10 CELLSPACING=20> + <TR><TD BGCOLOR="#e2e2e2" WIDTH=70%><BR><IMG SRC="images/stepfwd_on.png" WIDTH=16 HEIGHT=16 BORDER=0> Setup use of <I>saslauthd</I> on the PCP Collector:<BR> +<PRE><B> +# grep PCP_SASLCONF_DIR /etc/pcp.conf +PCP_SASLCONF_DIR=/etc/sasl2 + +# cat $PCP_SASLCONF_DIR/sasl2/pmcd.conf +pwcheck_method: saslauthd + +# $PCP_RC_DIR/pmcd restart +</B></PRE> +</TD></TR> +</TABLE> + +<P>We are now ready to establish an authenticated connection. +<I>saslauthd</I> will log into the system log, so any authorisation +failures can be further diagnosed using information captured there.</P> + +<TABLE WIDTH=100% BORDER=0 CELLPADDING=10 CELLSPACING=20> + <TR><TD BGCOLOR="#e2e2e2" WIDTH=70%><BR><IMG SRC="images/stepfwd_on.png" WIDTH=16 HEIGHT=16 BORDER=0> Setup use of <I>saslauthd</I> on the PCP Collector:<BR> +<PRE><B> +$ pminfo -h pcps://server.demo.net?method=plain -dfmt proc.fd.count +Username: jack +Password: xxxxxx + +proc.fd.count PMID: 3.51.0 [open file descriptors] + Data Type: 32-bit unsigned int InDom: 3.9 0xc00009 + Semantics: instant Units: count + inst [1281 or "001281 bash"] value 4 + inst [1287 or "001287 make -j 8 default_pcp"] value 5 + inst [1802 or "001802 bash"] value 4 + [...] +</B></PRE> +</TD></TR> +</TABLE> + +<I><B><A NAME="gssapi">Kerberos Authentication</A></B></I> +<P>The PCP collector system can be configured to authenticate using Kerberos +single-sign-on using the GSSAPI authentication mechanism. +This mechanism is enabled via the <I>mech_list</I> option in <I>/etc/sasl2/pmcd.conf</I>, +and the keytab should be set to <I>/etc/pcp/pmcd/krb5.tab</I>. + +<TABLE WIDTH=100% BORDER=0 CELLPADDING=10 CELLSPACING=20> + <TR><TD BGCOLOR="#e2e2e2" WIDTH=70%><BR><IMG SRC="images/stepfwd_on.png" WIDTH=16 HEIGHT=16 BORDER=0> Check for support:<BR> +<PRE><B> +$ pmconfig -L | egrep '^auth|^secure' +secure_sockets=true +authentication=true + +$ pluginviewer -s -m GSSAPI +[...] +Plugin "gssapiv2" [loaded], API version: 4 + SASL mechanism: GSSAPI, best SSF: 56, supports setpass: no + security flags: NO_ANONYMOUS|NO_PLAINTEXT|NO_ACTIVE|PASS_CREDENTIALS|MUTUAL_AUTH + features: WANT_CLIENT_FIRST|PROXY_AUTHENTICATION|DONTUSE_USERPASSWD +</B></PRE> +</TD></TR> +</TABLE> + +<TABLE WIDTH=100% BORDER=0 CELLPADDING=10 CELLSPACING=20> + <TR><TD BGCOLOR="#e2e2e2" WIDTH=70%><BR><IMG SRC="images/stepfwd_on.png" WIDTH=16 HEIGHT=16 BORDER=0> Setup Kerberos authentication on the PCP Collector:<BR> +<PRE><B> +# kadmin.local +kadmin.local: add_principal pmcd/server.demo.net +Enter password for principal "pmcd/server.demo.net@DEMO.NET": +Re-enter password for principal "pmcd/server.demo.net@DEMO.NET": +Principal "pmcd/server.demo.net@DEMO.NET" created. + +kadmin.local: ktadd -k /root/pmcd-server-demo.tab pmcd/server.demo.net@DEMO.NET +Entry for principal pmcd/server.demo.net@DEMO.NET with kvno 4, encryption type Triple DES cbc mode with HMAC/sha1 added to keytab WRFILE:/root/pmcd-server-demo.tab. +Entry for principal pmcd/server.demo.net@DEMO.NET with kvno 4, encryption type ArcFour with HMAC/md5 added to keytab WRFILE:/root/pmcd-server-demo.tab. +Entry for principal pmcd/server.demo.net@DEMO.NET with kvno 4, encryption type DES with HMAC/sha1 added to keytab WRFILE:/root/pmcd-server-demo.tab. +Entry for principal pmcd/server.demo.net@DEMO.NET with kvno 4, encryption type DES cbc mode with RSA-MD5 added to keytab WRFILE:/root/pmcd-server-demo.tab. + +kadmin.local: quit + +# scp /root/pmcd-server-demo.tab root@server.demo.net:/etc/pcp/pmcd/krb5.tab +# rm /root/pmcd-server-demo.tab + +$ kinit jack@DEMO.NET +Password for jack@DEMO.NET: xxxxxx + +$ klist +Ticket cache: FILE:/tmp/krb5cc_500 +Default principal: jack@DEMO.NET + +Valid starting Expires Service principal +02/07/13 20:46:40 02/08/13 06:46:40 krbtgt/DEMO.NET@DEMO.NET + renew until 02/07/13 20:46:40 + +$ pminfo -h 'pcps://server.demo.net?method=gssapi' -dfmt proc.fd.count + +proc.fd.count PMID: 3.51.0 [open file descriptors] + Data Type: 32-bit unsigned int InDom: 3.9 0xc00009 + Semantics: instant Units: count + inst [1281 or "001281 bash"] value 4 + inst [1287 or "001287 make -j 8 default_pcp"] value 5 + inst [1802 or "001802 bash"] value 4 + [...] +</B></PRE> +</TD></TR> +</TABLE> + +<P><BR></P> +<HR> +<CENTER> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0> + <TR> <TD WIDTH=50%><P>Copyright © 2007-2010 <A HREF="http://www.aconex.com/"><FONT COLOR="#000060">Aconex</FONT></A><BR>Copyright © 2000-2004 <A HREF="http://www.sgi.com/"><FONT COLOR="#000060">Silicon Graphics Inc</FONT></P></TD> + <TD WIDTH=50%><P ALIGN=RIGHT><A HREF="http://pcp.io/"><FONT COLOR="#000060">PCP Site</FONT></A><BR>Copyright © 2012-2014 <A HREF="http://www.redhat.com/"><FONT COLOR="#000060">Red Hat</FONT></P></TD> </TR> +</TABLE> +</CENTER> +</BODY> +</HTML> diff --git a/man/html/lab.importdata.html b/man/html/lab.importdata.html new file mode 100644 index 0000000..502ad19 --- /dev/null +++ b/man/html/lab.importdata.html @@ -0,0 +1,560 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> +<html> +<head> + <meta http-equiv="content-type" content="text/html; charset=utf-8"> + <meta http-equiv="content-style-type" content="text/css"> + <title>Importing Data and Creating PCP Archives</title> + <link href="pcpdoc.css" rel="stylesheet" type="text/css"> + <link href="images/pcp.ico" rel="icon" type="image/ico"> +</head> +<body lang="en-AU" text="#000060" dir="LTR"> +<table width="100%" border=0 cellpadding=0 cellspacing=0> + <tr> <td width=64 height=64><font color="#000080"><a href="http://pcp.io/"><img src="images/pcpicon.png" alt="pmcharticon" align=top width=64 height=64 border=0></a></font></td> + <td width=1><p> </p></td> + <td width=500><p style="vertical-align:middle; text-align:left;"><a href="index.html"><font color="#cc0000">Home</font></a> · <a href="lab.pmlogger.html"><font color="#cc0000">Archive Logger</font></a></p></td> + </tr> +</table> +<h1>Importing data and creating PCP archives</h1> +<table width="15%" border=0 cellpadding=5 cellspacing=10 align=right> + <tr><td bgcolor="#e2e2e2"><img src="images/system-search.png" alt="search" width=16 height=16 border=0> <i>Tools</i><br><pre> +PCP::LogImport +pmlogsummary +pmlogger +pmchart +pmie +perl +</pre></td></tr> +</table> +<p>For most performance data processed by the Performance Co-Pilot (PCP), +the information is gathered by domain-specific agents or Performance +Metric Domain Agents (PMDAs). The data and metadata (describing the +performance data) is then provided via the Performance Metric Co-ordinating Daemon (PMCD) directly to real-time PCP monitoring tools like <i>pmchart</i>, +<i>pmie</i>, <i>pmval</i>, etc. or written to PCP archive files +by <i>pmlogger</i> for +subsequent retrospective analysis using these same PCP tools. +</p> +<p>This document describes an alternative method of importing +performance data into PCP by creating PCP archives from files or data +streams that have no knowledge of PCP. +</p> +<ul> + <li><a href="#prereqs">Prerequisites</a> + <li><a href="#identify">Identify Metrics and Metadata</a> + <li><a href="#scripting">Getting Started Scripting</a> + <li><a href="#metadata">Revisiting the Metadata</a> + <li><a href="#instances">Multi-valued Metrics and Instance Domains</a> + <li><a href="#handles">Handles</a> + <li><a href="#timezones">Timezones</a> + <li><a href="#extras">Bells and Whistles</a> + <li><a href="#complete">Complete Solution</a> +</ul> +<p>The services needed to build an import tool are included in the +<i>libpcp_import</i> package and a Perl wrapper is provided in the <b>PCP::LogImport</b> +module. +The C and Perl APIs are effectively identical. +Refer to the <b>LOGIMPORT</b>(3) +manual page for an overview of these services. +The examples in this document will be given in Perl. +</p> +<p>Several import tools are already provided with PCP, namely: +</p> +<table border="1" cellspacing="1" cellpadding="5"> +<tr><th>Tool</th><th>Function</th> +</tr> +<tr><td><i>sheet2pcp</i></td> + <td>Import data from a spreadsheet in CSV, OpenOffice or Microsoft Office format.</td></tr> +<tr><td><i>sar2pcp</i></td> + <td>Import data from the <i>sadc</i> (System Activity Reporting Collector) + that is part of the <i>sysstat</i> package and modelled on the + classical Unix <i>sar</i> tools.</td></tr> +<tr><td><i>iostat2pcp</i></td> + <td>Import data from output of the <i>iostat</i> command + that is part of the <i>sysstat</i> package and modelled on the + Berkeley Unix command of the same name.</td></tr> +</table> + +<p> +These scripts are all written in Perl, and we shall refer to them in +this document to present examples of specific aspects of the LOGIMPORT +services or the issues to be considered when building an import tool. +</p> + +<p> +For the most part in this document we'll be developing an import tool +for log files from a file migration application. +Some sample log lines are shown below: +</p> +<table cellpadding=10><tr><td bgcolor="#e2e2e2"> +<pre> +2010-07-04 13:46:29 14 files (6, 8, 0) 142512 bytes (92098) +2010-07-04 13:46:59 51 files (28, 23, 0) 132761 bytes (33239) +2010-07-04 13:47:29 36 files (23, 12, 1) 5733152 bytes (5688400) +2010-07-04 13:47:59 49 files (40, 9, 0) 118418 bytes (70669) +2010-07-04 13:48:29 30 files (7, 23, 0) 210531 bytes (52261) +2010-07-04 13:48:59 23 files (6, 17, 0) 81048 bytes (15175) +2010-07-04 13:49:29 55 files (31, 24, 0) 190841 bytes (27908) +2010-07-04 13:49:59 54 files (49, 5, 0) 14078 bytes (1213) +2010-07-04 13:50:29 38 files (19, 19, 0) 82398 bytes (16781) +2010-07-04 13:50:59 0 files (0, 0, 0) 0 bytes (0) +2010-07-04 13:51:29 31 files (8, 23, 0) 202755 bytes (41984) +2010-07-04 13:51:59 0 files (0, 0, 0) 0 bytes (0) +2010-07-04 13:52:29 7 files (4, 3, 0) 15954 bytes (8789) +</pre> +</td></tr></table> + +<p>Each line begins with a date and time, then the count of +the number of files migrated over the last time interval, then +three counts in parenthesis corresponding to the number of small files +(less than 1024 bytes), medium files (less than 1024*1024 bytes) and +large (more than 1024*1024 bytes) files that were migrated, then the total +number of bytes moved and finally the size (in bytes) of the largest +file moved. +</p> + +<h2><a name="prereqs">Prerequisites</a></h2> + +<p>The input data stream needs to conform to some basic principles +before we can consider importing information to PCP:</p> + +<ul> +<li><b>Timestamps</b>. A PCP archive is a time-series of observations, hence +we need a date and time stamp for each observation. In the simplest +case there is a representation of +the date and time in the input records. Sometimes the date and time appears as a text string, +sometimes it is encoded in a binary file and +sometimes it requires some guesswork to reconstruct the date and time +of each observation (see <i>iostat2pcp</i> for example). +In all cases, it will be necessary to have the datestamp available in the +internal system clock format, namely seconds and microseconds since +the "epoch". Fortunately the Perl module <b>Date::Parse</b> +does a reasonable job of parsing dates and times in text format, +although some preprocessing of the date may +be required to force into an ISO 8601 compatible format (see <b>dodate()</b> +in <i>sheet2pcp</i>, <i>iostat2pcp</i> and <i>sar2pcp</i> for a +number of examples). +<p>We shall return to timestamps and the associated matter of <b>timezones</b> +a little later in this document. +</p> +</li> + +<li> +<b>Regular format</b>. +Some file formats (often application logs) can be quite difficult to parse +and extract the data you wish to import into PCP. Pre-processing can help +remove ambiguities, cull irrelevant information and make life generally easier. +As an example, <i>sar2pcp</i> uses <i>sadf</i> to translate the binary data +file from <i>sadc</i> into an XML stream that is much easier to process. +</li> +</ul> + +<h2><a name="identify">Identify PCP Metrics and Metadata</a></h2> + +<p> +Incremental development is encouraged. So we shall start with one +metric being the number of files migrated. +</p> + +<p>The first task is to assign +a name – the rules must conform to those for the Performance Metrics +Name Space (PMNS), namely a number of components separated by periods +"." with each component starting with an alphabetic followed +by zero or more characters drawn from the alphabetics, digits and the +underscore "_" character (see <b>pmns</b>(4) for more +details). For our metrics we'll use the prefix <b>mover.</b> and so the +first metric will be known as <b>mover.nfile</b>. +</p> + +<p> +Next the metadata for each metric must be defined. This is basically the +fields of a <b>pmDesc</b> data structure as defined in <b>pmLookupDesc</b>(3). +The following table describes the information required, some of the +options and the values chosen for <b>mover.nfile</b>. +</p> + +<table border="1" cellspacing="1" cellpadding="1" align="left"> +<tr align="center"> + <th>Metadata</th><th>Options</th><th>mover.nfile</th> +</tr> +<tr align="left"> + <td>Unique Performance Metric Identifier (PMID)</td> + <td><b>PM_ID_NULL</b> for a default assignment, else use the + <b>pmid_build</b> macro as described in <b>pmiAddMetric</b>(3). + </td> + <td><b>PM_ID_NULL</b></td> +</tr> +<tr> + <td>(Data) Type</td> + <td><b>PM_TYPE_32</b> for a 32-bit integer, etc. See <b>pmLookupDesc</b>(3) + for a full list and description. + </td> + <td><b>PM_TYPE_U32</b></td> +</tr> +<tr> + <td>Instance Domain (indom)</td> + <td>If there is only one value for the metric, then this should be + <b>PM_INDOM_NULL</b>, else it should be a value constructed using + the <b>pmInDom_build</b> macro, see <b>pmiAddMetric</b>(3). + </td> + <td><b>PM_INDOM_NULL</b></td> +</tr> +<tr> + <td>Semantics</td> + <td>Defines how to interpret consecutive values. If the values are + from a counter that is monotonically increasing, use + <b>PM_SEM_COUNTER</b>. If there is no relationship between one + observation and the next, use <b>PM_SEM_INSTANT</b>. As a special + case, if the value is most <u>unlikely</u> to change over time (e.g. a + configuration parameter), then use <b>PM_SEM_DISCRETE</b>. + </td> + <td><b>PM_SEM_INSTANT</b></td> +</tr> +<tr> + <td>Units</td> + <td>The interpretation of values for each metric is defined by + classifying the metric along three orthogonal axes, namely + <u>space</u>, <u>time</u> and <u>count</u> (for events, messages, calls, packets, etc.). + For each axis, we need to specify the <b>dimension</b> (0 for not + appropriate, -1 if the value is "per unit" along this axis + or 1 if the value is measured in units along this axis) and the + <b>scale</b> (if the dimension is not zero) to define the absolute + magnitude of values along this axis. Refer to <b>pmLookupDesc</b>(3) + for a full list of the available options. Use a <b>pmiUnits</b>(3) + constructor to build a units value. + </td> + <td><b>pmiUnits(0,0,1,0,0,PM_COUNT_ONE)</b></td> +</tr> +</table> +<p> </p> + +<h2><a name="scripting">Getting Started Scripting</a></h2> + +<p>The basic algorithm follows this template:</p> +<ul> + <li>Define metadata</li> + <li>Loop over input data + <ul> + <li>output values</li> + <li>write PCP archive record</li> + </ul> + </li> +</ul> + +<p>For our sample file migration data, the following minimalist Perl +script will do the job</p> + +<table cellpadding=10><tr><td bgcolor="#e2e2e2"> +<pre> +use strict; +use warnings; +use Date::Parse; +use Date::Format; +use PCP::LogImport; + +pmiStart("mover_v1", 0); +pmiAddMetric("mover.nfile", + PM_ID_NULL, PM_TYPE_U32, PM_INDOM_NULL, + PM_SEM_INSTANT, pmiUnits(0,0,1,0,0,PM_COUNT_ONE)); + +open(INFILE, "<mover.log"); +while (<INFILE>) { + my @part; + chomp; + @part = split(/\s+/, $_); + pmiPutValue("mover.nfile", "", $part[2]); + pmiWrite(str2time($part[0] . "T" . $part[1], "UTC"), 0); +} + +pmiEnd(); +</pre> +</td></tr></table> + +<p>The resultant archive contains one metric.</p> +<table cellpadding=10><tr><td bgcolor="#e2e2e2"> +<pre> +$ pminfo -d -a mover_v1 + +mover.nfile + Data Type: 32-bit unsigned int InDom: PM_INDOM_NULL 0xffffffff + Semantics: instant Units: count +</pre> +</td></tr></table> + +<p><table><tr style="vertical-align:top;"><td> +<p>And when plotted with <i>pmchart</i> produces a graph like +this ...</p> +</td><td> +<img src="images/mover.nfile.instant.png" alt="nfile.instant"> +</td></tr></table> +<p> </p> + +<h2><a name="metadata">Revisiting the Metadata</a></h2> + +<table><tr style="vertical-align:top;"><td> +<p>The number of files migrated in this example could be exported as either +the instantaneous value over the previous sample interval, or accumulated +as a running total. If the running total is used and +the semantics of the <b>mover.nfile</b> metric +remains <b>PM_SEM_INSTANT</b> the resultant archive produces a graph +like this ... +which is not generally useful for analysis!</p> +</td><td> +<img src="images/mover.nfile.step.png" alt="nfile.step" style="vertical-align:top;"> +</td></tr> +<tr style="vertical-align:top;"><td> +<p>So we change the data +semantics to be <b>PM_SEM_COUNTER</b> and rely on the fact that most +PCP monitoring tools will automatically rate convert counters before +displaying them. This produces a very similar +graph to the first one (the plot style is the only difference) when the output archive is +replayed with the same sample interval as found in the input log file (30 seconds). +</td><td> +<img src="images/mover.nfile.counter.png" alt="nfile.counter" style="vertical-align:top;"> +</td></tr> +<tr style="vertical-align:top;"><td> +<p>The real difference in the choice of data semantics can +seen when the sample interval for replay is longer than the sample +interval in the PCP archive. Using a replay interval of 180 seconds +(6 times the sample interval in the archive), produces the following +graph for the <b>PM_SEM_INSTANT</b> data.</p> +</td><td> +<img src="images/mover.nfile.instant.3min.png" alt="nfile.instant.3min" style="vertical-align:top;"> +<tr style="vertical-align:top;"><td> +<p>And the <b>PM_SEM_COUNTER</b> data is displayed like this.</p> +</td><td> +<img src="images/mover.nfile.counter.3min.png" alt="nfile.counter.3min" style="vertical-align:top;"> +</td></tr></table> + +<p> +For the <b>PM_SEM_INSTANT</b> metric, the only choice available to <i>pmchart</i> +(and indeed any PCP reporting tool) is to use the most recent observed +value at each reporting interval. In the example above, this means 5 +data values from the archive are skipped and the 6th value is used for +each reporting interval. By comparison, for a <b>PM_SEM_COUNTER</b> +metric, all the reporting tools sample the metric at the start of +the interval and at the end of the interval and then report the +linearly interpolated rate over the interval, which includes the "history" of what was observed in each of the 6 archive intervals for +each reporting interval.</p> + +<p>This can be seen more clearly when the data is tabulated rather than +plotted.</p> + +<table border=1 cellpadding=3> +<tr><th rowspan=3>Time</th><th colspan=2>PM_SEM_INSTANT</th><th colspan=4>PM_SEM_COUNTER</th></tr> +<tr><th>30sec samples</th><th>180sec samples</th><th colspan=2>30sec samples</th><th colspan=2>180sec samples</th></tr> +<tr><th>files</th><th>files</th><th>files/sec</th><th>files</th><th>files/sec</th><th>files</th></tr> +<tr align="center"><td>23:58:59.000</td><td>34</td><td> </td><td>1.133</td><td>34.0</td><td> </td><td> </td></tr> +<tr align="center"><td>23:59:29.000</td><td>5</td><td> </td><td>0.167</td><td>5.0</td><td> </td><td> </td></tr> +<tr align="center"><td>23:59:59.000</td><td>12</td><td> </td><td>0.400</td><td>12.0</td><td> </td><td> </td></tr> +<tr align="center"><td>00:00:29.000</td><td>39</td><td> </td><td>1.300</td><td>39.0</td><td> </td><td> </td></tr> +<tr align="center"><td>00:00:59.000</td><td>3</td><td> </td><td>0.100</td><td>3.0</td><td> </td><td> </td></tr> +<tr align="center"><td>00:01:29.000</td><td>0</td><td>0</td><td>0.000</td><td>0.0</td><td>0.517</td><td>93.0</td></tr> +<tr align="center"><td>00:01:59.000</td><td>10</td><td> </td><td>0.333</td><td>10.0</td><td> </td><td> </td></tr> +<tr align="center"><td>00:02:29.000</td><td>42</td><td> </td><td>1.400</td><td>42.0</td><td> </td><td> </td></tr> +<tr align="center"><td>00:02:59.000</td><td>42</td><td> </td><td>1.400</td><td>42.0</td><td> </td><td> </td></tr> +<tr align="center"><td>00:03:29.000</td><td>28</td><td> </td><td>0.933</td><td>28.0</td><td> </td><td> </td></tr> +<tr align="center"><td>00:03:59.000</td><td>28</td><td> </td><td>0.933</td><td>28.0</td><td> </td><td> </td></tr> +<tr align="center"><td>00:04:29.000</td><td>6</td><td>6</td><td>0.200</td><td>6.0</td><td>0.867</td><td>156.0</td></tr> +<tr align="center"><td>00:04:59.000</td><td>57</td><td> </td><td>1.900</td><td>57.0</td><td> </td><td> </td></tr> +<tr align="center"><td>00:05:29.000</td><td>0</td><td> </td><td>0.000</td><td>0.0</td><td> </td><td> </td></tr> +<tr align="center"><td>00:05:59.000</td><td>15</td><td> </td><td>0.500</td><td>15.0</td><td> </td><td> </td></tr> +<tr align="center"><td>00:06:29.000</td><td>27</td><td> </td><td>0.900</td><td>27.0</td><td> </td><td> </td></tr> +<tr align="center"><td>00:06:59.000</td><td>53</td><td> </td><td>1.767</td><td>53.0</td><td> </td><td> </td></tr> +<tr align="center"><td>00:07:29.000</td><td>57</td><td>57</td><td>1.900</td><td>57.0</td><td>1.16</td><td>209.0</td></tr> +</table> + + +<p>Where the semantics of the data matches that of a free-running counter +and where the total can easily be extracted from the input data source, +it is <b>always</b> better to export PCP metrics with the semantics +of <b>PM_SEM_COUNTER</b>. Note that the base value for a counter is +arbitrary and zero works just fine.</p> + +<p>Using similar arguments we can identify two additional singular metrics +that can be extracted from the log as <b>mover.nbyte</b> (a free-running +counter of the number of bytes migrated) and <b>mover.max_file_size</b> +(an instantaneous metric reporting the size of the largest file migrated +in the previous interval). With these additions, our minimalist Perl +script has become ...</p> + +<table cellpadding=10><tr><td bgcolor="#e2e2e2"> +<pre> +use strict; +use warnings; +use Date::Parse; +use Date::Format; +use PCP::LogImport; + +my $nfile = 0; +my $nbyte = 0; + +pmiStart("mover_v3", 0); +pmiAddMetric("mover.nfile", + PM_ID_NULL, PM_TYPE_U32, PM_INDOM_NULL, + PM_SEM_COUNTER, pmiUnits(0,0,1,0,0,PM_COUNT_ONE)); +pmiAddMetric("mover.nbyte", + PM_ID_NULL, PM_TYPE_U64, PM_INDOM_NULL, + PM_SEM_COUNTER, pmiUnits(1,0,0,PM_SPACE_BYTE,0,0)); +pmiAddMetric("mover.max_file_size", + PM_ID_NULL, PM_TYPE_U64, PM_INDOM_NULL, + PM_SEM_INSTANT, pmiUnits(1,0,0,PM_SPACE_BYTE,0,0)); + +open(INFILE, "<mover.log"); +while (<INFILE>) { + my @part; + chomp; + s/[(),]//g; # remove all (, ) and , + @part = split(/\s+/, $_); + $nfile += $part[2]; + pmiPutValue("mover.nfile", "", $nfile); + $nbyte += $part[7]; + pmiPutValue("mover.nbyte", "", $nbyte); + pmiPutValue("mover.max_file_size", "", $part[9]); + pmiWrite(str2time($part[0] . "T" . $part[1], "UTC"), 0); +} + +pmiEnd(); +</pre> +</td></tr></table> + +<p> +This produces a PCP archive that can be plotted with <i>pmchart</i> +to produce the following graph.</p> +<p><center> +<img src="images/mover.v3.png" alt="mover.v3"> +</center></p> + +<h2><a name="instances">Multi-valued Metrics and Instance Domains</a></h2> + +<p>Metrics that have more than one value are supported in PCP through +the concept of an Instance Domain (or <b>indom</b>) which is a +set with an internal unique identifier (an integer) and a unique external +name (a string) for each instance that may have an associated values. +There can be many Instance Domains. And many metrics can be associated +with the same Instance Domain.</p> + +<p>The remaining metric in our example is <b>mover.nfile_by_size</b> +which has the same metadata as <b>mover.nfile</b> except there is +an associated Instance Domain to accommodate the 3 values +("<=1Kbyte", "<=1Mbyte" and +">1Mbyte"). +The Instance Domain identifier is constructed using the <b>pmInDom_build</b> +macro, and then used in calls to <b>pmiAddInstance</b>(3) to make the association +for each metric-instance pair. +The relevant metadata declarations are +as follows:</p> + +<table cellpadding=10><tr><td bgcolor="#e2e2e2"> +<pre> +my $sz_indom = pmInDom_build(PMI_DOMAIN, 0); +my @nfile_by_size = (0,0,0); + +pmiAddMetric("mover.nfile_by_size", + PM_ID_NULL, PM_TYPE_U32, $sz_indom, + PM_SEM_COUNTER, pmiUnits(0,0,1,0,0,PM_COUNT_ONE)); +pmiAddInstance($sz_indom, "<=1Kbyte", 0); +pmiAddInstance($sz_indom, "<=1Mbyte", 1); +pmiAddInstance($sz_indom, ">1Mbyte", 2); +</pre> +</td></tr></table> + +<p>And then in the loop, these additional calls to <b>pmiPutValue</b>(3) +are required: + +<table cellpadding=10><tr><td bgcolor="#e2e2e2"> +<pre> +$nfile_by_size[0] += $part[4]; +pmiPutValue("mover.nfile_by_size", "<=1Kbyte", $nfile_by_size[0]); +$nfile_by_size[1] += $part[5]; +pmiPutValue("mover.nfile_by_size", "<=1Mbyte", $nfile_by_size[1]); +$nfile_by_size[2] += $part[6]; +pmiPutValue("mover.nfile_by_size", ">1Mbyte", $nfile_by_size[2]); +</pre> +</td></tr></table> + +<p> +This produces our final PCP archive that can be plotted with <i>pmchart</i> +to produce the following graph.</p> +<p><center> +<img src="images/mover.png" alt="mover"> +</center></p> + +<h2><a name="handles">Handles</a></h2> + +<p>If there is a lot of data and/or a lot of PCP metrics, the calls +to <b>pmiPutValue</b>(3) in the inner loop of the import application +may become expensive as a consequence of the repeated text-based +lookup for a metric name and an instance name.</p> + +<p>The <b>LOGIMPORT</b>(3) infrastructure provides a "handles" +mechanism that may be used to improve efficiency. +<b>pmiGetHandle</b>(3) may be used to obtain a "handle" for +a metric-instance pair (once the metric and instance have been defined), +then <b>pmiPutValueHandle</b>(3) may be used instead of <b>pmiPutValue</b>(3).</p> + +<h2><a name="timezones">Timezones</a></h2> + +<p>The interpretation of the timestamps in the output PCP archive is +dependent on the timezone in which PCP believes the archive was created.</p> + +<p>Since many import log files do not report the timezone, the <b>LOGIMPORT</b>(3) +services assume a default timezone of <b>UTC</b>. +An alternative timezone may be specified using <b>pmiSetTimezone</b>(3), +but a corresponding adjustment needs to be made to the date and time +conversions when arriving at the timestamp for each sample, e.g. +using <b>str2time</b>() and/or <b>ctime</b>(). +Unfortunately the format for the timezone offset is not handled +the same in all places – for the ugly details, +refer to the <b>–Z</b> command line +processing and the <b>do_label</b>() procedure in the +complete <a href="importdata/mover2pcp">mover2pcp</a> example code.</p> + +<h2><a name="extras">Bells and Whistles</a></h2> + +<p>The Perl code we've been using thus far is minimalist and needs +several extensions to make the application robust. Specifically these +include:</p> + +<ul> +<li>For singular metrics, wrap the <b>pmiAddMetric</b>(3) calls in +error handling logic, +handle the per-metric metadata variations +and create the handle for later use, see the <b>def_single</b>() +procedure.</li> + +<li>The <b>def_multi</b>() procedure performs a similar function for +multi-valued metrics, except the handle creation is deferred until +each instance is processed.</li> + +<li>For each metric-instance pair associated with a multi-valued +metric, the <b>def_metric_inst</b>() procedure maintains a cache of +indoms and instances for those indoms so that internal instance +identifiers can be allocated automatically and <b>pmiAddInstance</b>(3) +is only called the first time each unique instance is observed for +each instance domain. Also there is error checking logic here and +a new handle is allocated for each metric-instance pair.</li> + +<li>The <b>put</b>() procedure is a wrapper around +<b>pmiPutValueHandle</b>(3) that includes some error handling +and stepping through the array of handles created earlier.</li> + +<li>Timezone and archive label details are addressed in the +<b>do_label</b>() procedure.</li> + +<li>Add error checking at the end of the loop after each +value has been added to the next output record.</li> + +</ul> + +<h2><a name="complete">Complete Solution</a></h2> + +<p>The complete mover2pcp Perl script can be viewed <a href="importdata/mover2pcp">here</a>.</p> + +<hr> +<CENTER> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0> + <TR> <TD WIDTH=50%><P>Copyright © 2007-2010 <A HREF="http://www.aconex.com/"><FONT COLOR="#000060">Aconex</FONT></A><BR>Copyright © 2000-2004 <A HREF="http://www.sgi.com/"><FONT COLOR="#000060">Silicon Graphics Inc</FONT></P></TD> + <TD WIDTH=50%><P ALIGN=RIGHT><A HREF="http://pcp.io/"><FONT COLOR="#000060">PCP Site</FONT></A><BR>Copyright © 2012-2014 <A HREF="http://www.redhat.com/"><FONT COLOR="#000060">Red Hat</FONT></P></TD> </TR> +</TABLE> +</CENTER> +</BODY> +</HTML> diff --git a/man/html/lab.mmapvalues.html b/man/html/lab.mmapvalues.html new file mode 100644 index 0000000..a304ac4 --- /dev/null +++ b/man/html/lab.mmapvalues.html @@ -0,0 +1,44 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> +<HTML> +<HEAD> + <meta http-equiv="content-type" content="text/html; charset=utf-8"> + <meta http-equiv="content-style-type" content="text/css"> + <link href="pcpdoc.css" rel="stylesheet" type="text/css"> + <link href="images/pcp.ico" rel="icon" type="image/ico"> + <TITLE>Memory Mapped Values</TITLE> +</HEAD> +<BODY LANG="en-AU" TEXT="#000060" DIR="LTR"> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 STYLE="page-break-before: always"> + <TR> <TD WIDTH=64 HEIGHT=64><FONT COLOR="#000080"><A HREF="http://pcp.io/"><IMG SRC="images/pcpicon.png" NAME="pmcharticon" ALIGN=TOP WIDTH=64 HEIGHT=64 BORDER=0></A></FONT></TD> + <TD WIDTH=1><P> </P></TD> + <TD WIDTH=500><P VALIGN=MIDDLE ALIGN=LEFT><A HREF="index.html"><FONT COLOR="#cc0000">Home</FONT></A> · <A HREF="lab.pmchart.html"><FONT COLOR="#cc0000">Charts</FONT></A> · <A HREF="timecontrol.html"><FONT COLOR="#cc0000">Time Control</FONT></A></P></TD> + </TR> +</TABLE> +<H1 ALIGN=CENTER STYLE="margin-top: 0.48cm; margin-bottom: 0.32cm"><FONT SIZE=7>Memory Mapped Values</FONT></H1> +<TABLE WIDTH=15% BORDER=0 CELLPADDING=5 CELLSPACING=10 ALIGN=RIGHT> + <TR><TD BGCOLOR="#e2e2e2"><IMG SRC="images/system-search.png" WIDTH=16 HEIGHT=16 BORDER=0> <I>Tools</I><BR><PRE> +pmdammv +mmvdump +java +perl +</PRE></TD></TR> +</TABLE> +<P>Introductory text. This is a placeholder. TODO... +</P> + +<P><BR></P> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 BGCOLOR="#e2e2e2"> + <TR><TD WIDTH=100% BGCOLOR="#081c59"><P ALIGN=LEFT><FONT SIZE=5 COLOR="#ffffff"><B>Next Section</B></FONT></P></TD></TR> +</TABLE> +<P>Next paragraph.</P> + +<P><BR></P> +<HR> +<CENTER> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0> + <TR> <TD WIDTH=50%><P>Copyright © 2007-2010 <A HREF="http://www.aconex.com/"><FONT COLOR="#000060">Aconex</FONT></A><BR>Copyright © 2000-2004 <A HREF="http://www.sgi.com/"><FONT COLOR="#000060">Silicon Graphics Inc</FONT></P></TD> + <TD WIDTH=50%><P ALIGN=RIGHT><A HREF="http://pcp.io/"><FONT COLOR="#000060">PCP Site</FONT></A><BR>Copyright © 2012-2014 <A HREF="http://www.redhat.com/"><FONT COLOR="#000060">Red Hat</FONT></P></TD> </TR> +</TABLE> +</CENTER> +</BODY> +</HTML> diff --git a/man/html/lab.pmchart.html b/man/html/lab.pmchart.html new file mode 100644 index 0000000..0a5e97f --- /dev/null +++ b/man/html/lab.pmchart.html @@ -0,0 +1,243 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> +<HTML> +<HEAD> + <meta http-equiv="content-type" content="text/html; charset=utf-8"> + <meta http-equiv="content-style-type" content="text/css"> + <link href="pcpdoc.css" rel="stylesheet" type="text/css"> + <link href="images/pcp.ico" rel="icon" type="image/ico"> + <TITLE>PCP Strip Charts</TITLE> +</HEAD> +<BODY LANG="en-AU" TEXT="#000060" DIR="LTR"> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 STYLE="page-break-before: always"> + <TR> <TD WIDTH=64 HEIGHT=64><FONT COLOR="#000080"><A HREF="http://pcp.io/"><IMG SRC="images/pmcharticon.png" NAME="pmcharticon" ALIGN=TOP WIDTH=64 HEIGHT=64 BORDER=0></A></FONT></TD> + <TD WIDTH=1><P> </P></TD> + <TD WIDTH=500><P VALIGN=MIDDLE ALIGN=LEFT><A HREF="index.html"><FONT COLOR="#cc0000">Home</FONT></A> · <A HREF="lab.pmchart.html"><FONT COLOR="#cc0000">Charts</FONT></A> · <A HREF="timecontrol.html"><FONT COLOR="#cc0000">Time Control</FONT></A></P></TD> + </TR> +</TABLE> +<H1 ALIGN=CENTER STYLE="margin-top: 0.48cm; margin-bottom: 0.32cm"><FONT SIZE=7>PCP Strip Charts</FONT></H1> +<TABLE WIDTH=15% BORDER=0 CELLPADDING=5 CELLSPACING=10 ALIGN=RIGHT> + <TR><TD BGCOLOR="#e2e2e2"><IMG SRC="images/system-search.png" WIDTH=16 HEIGHT=16 BORDER=0> <I>Tools</I><BR><PRE> +pmchart +pmtime +pmlogger +pmafm +</PRE></TD></TR> +</TABLE> +<P>The following tutorial introduces the basic functionality available in the PCP Strip Chart tool, <I>pmchart</I>.</P> +<UL> + <LI><A HREF="#main">Main Window</A> + <LI><A HREF="#views">Views</A> + <UL> + <LI><A HREF="#viewspec">View Specification</A> + </UL> + <LI><A HREF="#record">Recording</A> + <LI><A HREF="#saving">Saving Views</A> + <LI><A HREF="#custom">Custom Charts</A> + <LI><A HREF="#playback">Playback Recording</A> + <UL> + <LI><A HREF="#pmtime">Time Control</A> + </UL> + <LI><A HREF="#next">Next Steps</A> +</UL> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=10 CELLSPACING=20> + <TR><TD BGCOLOR="#e2e2e2" WIDTH=70%><BR><IMG SRC="images/stepfwd_on.png" WIDTH=16 HEIGHT=16 BORDER=0> Once PCP and PCP GUI packages have been successfully <A HREF="installation.html"><FONT COLOR="#000060">installed</FONT></A>, run the <I>pmchart</I> command or click on the <I>PCP Charts</I> icon to begin.</TD></TR> +</TABLE> + +<P><BR></P> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 BGCOLOR="#e2e2e2"> + <TR><TD WIDTH=100% BGCOLOR="#081c59"><P ALIGN=LEFT><FONT SIZE=5 COLOR="#ffffff"><B><A NAME="main">Main Window</A></B></FONT></P></TD></TR> +</TABLE> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0> + <TR> <TD><P>On starting the PCP Chart (pmchart) tool with no command line arguments, the initial display shows a menu, toolbar, and a live time axis.</P> +<P>The vacant area above the time axis is the blank canvas for your charts – we'll get to this shortly, but take a moment to digest the main window.</P> +<P>The time axis along the bottom of the window scrolls with the current time, updated every second, by default (this is also called the <I>sample interval</I>).</P> +<P>To the left of the time axis is the time control status button.</P><P>The blue arrow signifies that (live) time is moving forward. Pressing the button once will show the Time Control tool, <i>pmtime</i>, pressing it a second time hides it.</P> + </TD> + <TD WIDTH=372><P VALIGN=MIDDLE ALIGN=RIGHT><CENTER><BR><IMG ALIGN=RIGHT SRC="images/pmchart_blank_canvas.png" BORDER=0></CENTER></P></TD> + </TR> +</TABLE> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 STYLE="page-break-before: always"> + <TR> <TD WIDTH=312><P VALIGN=MIDDLE ALIGN=LEFT><CENTER><BR><IMG ALIGN=RIGHT SRC="images/pmtime_live.png" BORDER=0></CENTER></P></TD> + <TD WIDTH=10></TD> + <TD><P><BR><P>The time controls allow you to modify various aspects of the flow of time in your charts, and clearly displays the current time position.</P> +<P>A VCR paradigm is used to allow stopping and starting the flow of time, and in the case of historical data (PCP archives), allow movement both forwards and backwards through time, and allow fast, slow, or step-by-step updates to the displayed data.</P></TD> + </TR> +</TABLE> +<P><BR></P> +<A name="views"></A> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 BGCOLOR="#e2e2e2"> + <TR><TD WIDTH=100% BGCOLOR="#081c59"><P ALIGN=LEFT><FONT SIZE=5 COLOR="#ffffff"><B><A NAME="views">Views</A></B></FONT></P></TD></TR> +</TABLE> +<P>The toolbar along the top of the window has a blue folder icon for <I>Views</I>. The </B>File</B> menu provides access to the same functionality via the "Open View" item. +<TABLE WIDTH=100% BORDER=0 CELLPADDING=10 CELLSPACING=20> + <TR><TD BGCOLOR="#e2e2e2" WIDTH=70%><BR><IMG SRC="images/stepfwd_on.png" WIDTH=16 HEIGHT=16 BORDER=0> Click on the blue <I>Views</I> folder to bring up the “Open View” window.</TD></TR><BR> +</TABLE> +<P>This window initially displays a list of common performance views (these are the pre-installed <I>System Views</I>). These views have been found to be useful by others over many years, and will be able to run on any host or archive that provides the metrics and instances that they wish to plot - they will never specify specific hostnames, nor will they request any specific geometry or screen position. +<CENTER><IMG SRC="images/pmchart_open_view.png" BORDER=0></CENTER> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=10 CELLSPACING=20> + <TR><TD BGCOLOR="#e2e2e2" WIDTH=70%><BR><IMG SRC="images/stepfwd_on.png" WIDTH=16 HEIGHT=16 BORDER=0> +Select <I>CPU</I> and <I>Disk</I> from the list (Ctrl-Click allows multiple selections to be made), then press OK.<BR></TD></TR> +</TABLE> +<P>The chart canvas in the main window is now filled with the two selected Views, showing several aspects of processor and disk utilisation.</P> +<P><A NAME="viewspec"><B>What is a view?</B></A></P> +<P>A view is a complete <A HREF="views.html">specification</A> of every aspect of one or more charts, each of which can contains one or more plots. All properties of the charts and the individual plots are described - the data source behind the performance data, the color of the plots, the chart title, the style of the chart, whether the value axis (Y-Axis) should be scaled, whether there is a title, etc, etc. Some properties are optional (e.g. the title) and some can be specified as variable (e.g. allowing any host to be the source of the data).</P> +<P>Views are stored as plain text files in the local filesystem. The System Views are different only in that they are installed into a fixed location. There is a fixed place for custom views as well, below your home directory, where views you create in pmchart will be stored. If you look into the <I>Open View</I> dialog again, you'll see two icons to the right of the Path in the Open View dialog – these indicate whether the current path points to the System View location, the User View location, or neither. Notice how they update as you navigate through your files.</P> +<P><BR></P> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 BGCOLOR="#e2e2e2"> + <TR><TD WIDTH=100% BGCOLOR="#081c59"><P ALIGN=LEFT><FONT SIZE=5 COLOR="#ffffff"><B><A NAME="record">Recording</A></B></FONT></P></TD></TR> +</TABLE> +<P><B><FONT SIZE=4>Setup recording for later playback</FONT></B></P> +<P>A recording captures live performance data from the current View into an <B>archive folio</B>. A folio is a group of one or more performance data archives (sometimes refered to as "logs" – an ambiguous term, so we'll refer to them as archives from here on), a copy of the current View specification, and a configuration file for the <B>pmlogger</B> process which does the actual recording. A folio contains enough state to be able to replay the recording at any time in the future, exactly as it was recorded.</P> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=10 CELLSPACING=20> + <TR><TD BGCOLOR="#e2e2e2" WIDTH=70%><BR><IMG SRC="images/stepfwd_on.png" WIDTH=16 HEIGHT=16 BORDER=0> From the main menu, select <I>Record</I>, and then <I>Start</I> to initiate a recording.<BR></TD></TR> +</TABLE> +<P>The <I>Start Recording</I> dialog allows you to set various aspects of the recording session – we wont change these for now – just press the OK button. You'll notice the Live Time Control button in the botton left now displays a red light, indicating that recording is in progress. Let's leave the recording run while we investigate other parts of the tool – we'll come back to this later, when its had a chance to gather some interesting data.</P> +<P><B><FONT SIZE=4>Generating load for later playback</FONT></B></P> +<P>As a simple example of both the recording functionality, and of using pmchart to monitor different subsystems simultaneously, we'll generate some local disk I/O and see how this affects the disk and CPU utilisation charts we have already opened. +</P> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=10 CELLSPACING=20> + <TR><TD BGCOLOR="#e2e2e2" WIDTH=70%><BR><IMG SRC="images/stepfwd_on.png" WIDTH=16 HEIGHT=16 BORDER=0> In a command shell enter:<BR> +<PRE><B> +$ find / -xdev >/dev/null 2>&1 +</PRE></B> +</TD></TR> +</TABLE> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 STYLE="page-break-before: always"> + <TR> <TD WIDTH=377><P VALIGN=MIDDLE ALIGN=RIGHT><CENTER><BR><IMG ALIGN=RIGHT SRC="images/pmchart_cpu_disk.png" BORDER=0></CENTER></P></TD> + <TD WIDTH=15></TD> + <TD><P><BR><P>This command scans every inode on the root filesystem, which is usually a local disk. We observe a large increase in disk read operations as each inode is read in from disk (yellow plot in the <I>Disk</I> chart).</P><P>At the same time we observe a small increase in processor utilisation, in both kernel and user mode (red and navy blue in the <I>CPU</I> chart), as the command executes the code to read directories and query the <B>stat</B>(2) information for each file. Since we account for all CPU time, these increases in system and user time cause a corresponding decrease in the idle time (green area in the <I>CPU</I> chart).</P><P>There is also now an increase in the amount of time spent executing interrupt handlers (yellow plot in the <I>CPU</I> chart) since the device must generate an interrupt completion event for every I/O.</P><P>On systems that support a separate I/O wait CPU utilisation metric (Linux 2.6+ and IRIX), we also see a significant amount of time is spent with outstanding I/O requests (cyan plot in the <I>CPU</I> chart).</P></TD> + </TR> +</TABLE> +<P><BR></P> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 BGCOLOR="#e2e2e2"> + <TR><TD WIDTH=100% BGCOLOR="#081c59"><P ALIGN=LEFT><FONT SIZE=5 COLOR="#ffffff"><B><A NAME="saving">Saving Views</A></B></FONT></P></TD></TR> +</TABLE> +<P><I>Views</I> can be saved to (text) files for use on subsequent invocations of pmchart, or for use with different hosts or archives. +</P> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=10 CELLSPACING=20> + <TR><TD BGCOLOR="#e2e2e2" WIDTH=70%><BR><IMG SRC="images/stepfwd_on.png" WIDTH=16 HEIGHT=16 BORDER=0> +From the <I>File</I> menu select the <I>Save View</I> option.<BR> +Save the current two charts to a View named <I>/tmp/ExampleView</I>.<BR> +In a command shell, take a look through the saved View configuration. +<PRE><B> + $ cat /tmp/ExampleView</B> +<BR> #kmchart +<BR> version 1 +<BR> chart title "CPU Utilization [%h]" style utilization +<BR> plot legend "User" color #2d2de2 metric kernel.all.cpu.user +<BR> plot legend "Kernel" color #e71717 metric kernel.all.cpu.sys +<BR> plot legend "Nice" color #c2f3c2 metric kernel.all.cpu.nice +<BR> plot legend "Intr" color #cdcd00 metric kernel.all.cpu.intr +<BR> plot legend "Wait" color #00cdcd metric kernel.all.cpu.wait.total +<BR> plot legend "Idle" color #16d816 metric kernel.all.cpu.idle +<BR> chart title "IOPS over all Disks [%h]" style stacking +<BR> plot legend "Reads" color #ffff00 metric disk.all.read +<BR> plot legend "Writes" color #ee82ee metric disk.all.write +</PRE> +</TD></TR> +</TABLE> + +<P><BR></P> +<A name="charts"></A> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 BGCOLOR="#e2e2e2"> + <TR><TD WIDTH=100% BGCOLOR="#081c59"><P ALIGN=LEFT><FONT SIZE=5 COLOR="#ffffff"><B><A NAME="custom">Custom Charts</A></B></FONT></P></TD></TR> +</TABLE> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=10 CELLSPACING=20> + <TR><TD BGCOLOR="#e2e2e2" WIDTH=70%><BR><IMG SRC="images/stepfwd_on.png" WIDTH=16 HEIGHT=16 BORDER=0> From the <I>Edit</I> menu select the <I>Chart</I> item.<BR></TD></TR> +</TABLE> +<P>A tabbed window with all settings for the Disk chart is displayed. In the tree view on the left side of the window are the metrics from our selected Disk chart. +<BR><CENTER><IMG SRC="images/pmchart_edit_chart.png" BORDER=0></CENTER></P> +<P>The three tabs on the right side of the window show the current settings for this chart in three categories:<UL><LI>Properties relating to the entire chart (Title, Legend settings, Y-Axis scaling, etc); + <LI>Available metrics (performance data) for plotting in the chart + <LI>Properties related to each individual chart plot (color, label) +</UL> +<P>Dismiss the Edit Chart dialog – instead of modifying our existing charts, we'll build one from the ground up.</P> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=10 CELLSPACING=20> + <TR><TD BGCOLOR="#e2e2e2" WIDTH=70%><BR><IMG SRC="images/stepfwd_on.png" WIDTH=16 HEIGHT=16 BORDER=0> Click on the <I>New Chart</I> option in the toolbar to display the chart creation window.<BR></TD></TR> +</TABLE> +<P>It looks just like the chart editing window we've just seen, except initially we have no metrics selected in the chart, and default values for all of the chart properties.<BR><CENTER><IMG SRC="images/pmchart_new_chart.png" BORDER=0></CENTER></P> +<P>In the Available Metrics list on the Metrics tab, expand the <I>kernel,</I> <I>all</I>, <I>load</I> trees from your local hosts metric namespace, and then select the three load averages (<I>1, 5, 15 minutes</I>). Since these are leaf nodes in the namespace, and identify valid values for plotting, several buttons now become enabled – in particular the “Add Metric” button and the “Metric Info” button.<BR><CENTER><IMG SRC="images/pmchart_new_chart_select.png" BORDER=0></CENTER></P> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=10 CELLSPACING=20> + <TR><TD BGCOLOR="#e2e2e2" WIDTH=70%><BR><IMG SRC="images/stepfwd_on.png" WIDTH=16 HEIGHT=16 BORDER=0> Click on the “Metric Info” button to view the metric descriptor (<I>pminfo</I>) and current values (<I>pmval</I>) for <I>disk.all.total</I>. Dismiss that dialog, and then press the “Add Metric” button, to add this metric into the list of metrics for our new chart.<BR></TD></TR> +</TABLE> +<P>A default color is selected (this is chosen from the charts Color scheme, which can be set on the first tab) – this color can also be explicitly set by:<UL><LI>selecting the metric from the Chart Plots tree + <LI>selecting a new color from the color palette on the Plot tab + <LI>pressing the Apply color button +</UL> +<P>This change can also be reverted by using the revert color button, which returns it to its previous color (displayed alongside that button).</P> +<BR><CENTER><IMG SRC="images/pmchart_new_chart_colors.png" BORDER=0></CENTER></P> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=10 CELLSPACING=20> + <TR><TD BGCOLOR="#e2e2e2" WIDTH=70%><BR><IMG SRC="images/stepfwd_on.png" WIDTH=16 HEIGHT=16 BORDER=0> Set the label for the plots as “1 Min”, “5 Min” and “15 Min”, then press OK.<BR></TD></TR> +</TABLE> +<P>A new chart will appear at the bottom of the main window with one plot, and on the next sample interval current values will be plotted.</P> +<BR><CENTER><IMG SRC="images/pmchart_cpu_disk_load.png" BORDER=0></CENTER> +<P><BR></P> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 BGCOLOR="#e2e2e2"> + <TR><TD WIDTH=100% BGCOLOR="#081c59"><P ALIGN=LEFT><FONT SIZE=5 COLOR="#ffffff"><B><A NAME="playback">Playback Recording</A></B></FONT></P></TD></TR> +</TABLE> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=10 CELLSPACING=20> + <TR><TD BGCOLOR="#e2e2e2" WIDTH=70%><BR><IMG SRC="images/stepfwd_on.png" WIDTH=16 HEIGHT=16 BORDER=0> Click on the <I>Record</I> menu, then </I>Stop</I>.<BR></TD></TR> +</TABLE> +<CENTER><IMG SRC="images/pmchart_stop_recording.png" BORDER=0></CENTER> +<P>The dialog shown explains the status of your recording session (started earlier). At any time while recording, you also have the option of querying the recording process to see the same status, and also to detach the recording from the control of pmchart. But for now, we've simply ended the recording (note the red indicator light is now off on the time control button), and we're left with an archive containing the history from our recording, which we can now replay.</P> + +<TABLE WIDTH=100% BORDER=0 CELLPADDING=10 CELLSPACING=20> + <TR><TD BGCOLOR="#e2e2e2" WIDTH=70%><BR><IMG SRC="images/stepfwd_on.png" WIDTH=16 HEIGHT=16 BORDER=0> End your pmchart process now, open a command shell and run:<BR> +<PRE><B> +$ pmafm ~/.pcp/pmlogger/20100826.10.11.28.folio replay</B><BR></TD></TR> +</B></PRE> +</TABLE> +<P>(substituting the current recording timestamp into the folio file name from your earlier recording session)</P> +<BR><CENTER><IMG SRC="images/pmchart_cpu_disk_record.png" BORDER=0></CENTER> +<P>You are now in archive replay mode. Initially the time is stopped at the start of the archive, and the chart canvas area displays the recorded data in the views which were active at the time recording begun.</P> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=10 CELLSPACING=20> + <TR><TD BGCOLOR="#e2e2e2" WIDTH=70%><BR><IMG SRC="images/stepfwd_on.png" WIDTH=16 HEIGHT=16 BORDER=0> Click on the "Archive" Time Control push button in the bottom right corner to show the Time Controls.<BR></TD></TR> +</TABLE> +<P><A NAME="pmtime"><B><FONT SIZE=4>Time Control</FONT></B></A></P> +<P>We are now presented with the Time Control window, which is actually a separate process (<I>pmtime</I>). This program controls the flow of time in pmchart. +</P> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 STYLE="page-break-before: always"> + <TR><TD WIDTH=350><P VALIGN=MIDDLE ALIGN=LEFT><CENTER><BR><IMG ALIGN=LEFT SRC="images/pmtime_archive.png" BORDER=0></CENTER></P></TD> + <TD><BR><P>There are several modes of playback available in archive mode:<UL><LI>Normal mode, where time updates are sent to the client at a continuous rate (usually not too different to the original live recording), as determined by the "Speed" wheel setting. + <LI>Step mode, where time is only advanced/retreated (by clicking on the Step button) one sample at a time. + <LI>Fast mode, where time is moved quickly in either a fast forward or fast rewind direction, and the visible charts are updated as quickly as possible. +</UL></P><P>The Speed setting can be changed by directly editing the text entry box, or more simply by selecting and rotating the wheel either left or right. Speed is only relevent in Normal mode.</TD> + </TR> +</TABLE> +</P> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=10 CELLSPACING=20> + <TR><TD BGCOLOR="#e2e2e2" WIDTH=70%><BR><IMG SRC="images/stepfwd_on.png" WIDTH=16 HEIGHT=16 BORDER=0> Press the Play button.<BR></TD></TR> +</TABLE> +<P>We now see the pmchart Disk and CPU charts displaying the recorded data, one sample after another, and the chart appears to be moving from right to left as time advances at the leading (right) edge of the time axis. +<P>We can increase the speed of the playback by moving the Time Controls wheel from left to right, and vice-versa to reduce the playback speed</B> +</P> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=10 CELLSPACING=20> + <TR><TD BGCOLOR="#e2e2e2" WIDTH=70%><BR><IMG SRC="images/stepfwd_on.png" WIDTH=16 HEIGHT=16 BORDER=0> Press the Stop button.<BR></TD></TR> +</TABLE> +<P>We have now effectively paused, showing a number of Visible Points from the current sample time (displayed in both the Time Control window and the time axis, in the bottom right of the pmchart display) backward in time. +</P> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=10 CELLSPACING=20> + <TR><TD BGCOLOR="#e2e2e2" WIDTH=70%><BR><IMG SRC="images/stepfwd_on.png" WIDTH=16 HEIGHT=16 BORDER=0> Use the Position slider in the Time Control window to move toward the end of the archive.<BR>Press the Back button.<BR></TD></TR> +</TABLE> +<P>Now time appears to be moving backward, with time updates scrolling past in the pmchart time axis from left to right, until we reach the start of the archive. At that point, playback will stop and the Time Controls will be updated accordingly. + +<P><BR></P> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 BGCOLOR="#e2e2e2"> + <TR><TD WIDTH=100% BGCOLOR="#081c59"><P ALIGN=LEFT><FONT SIZE=5 COLOR="#ffffff"><B><A NAME="next">Next Steps</A></B></FONT></P></TD></TR> +</TABLE> +<P>This introductory tutorial has touched on the basics of using this handy analysis tool. Many functions have not been discussed at all, or only briefly touched on – feel free to investigate these areas in detail now:<BR> +<UL> + <LI>Multiple Tabs + <LI>Different chart styles + <LI>Monitoring multiple hosts simultaneously +</UL> +<P><BR></P> +<HR> +<CENTER> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0> + <TR> <TD WIDTH=50%><P>Copyright © 2007-2010 <A HREF="http://www.aconex.com/"><FONT COLOR="#000060">Aconex</FONT></A><BR>Copyright © 2000-2004 <A HREF="http://www.sgi.com/"><FONT COLOR="#000060">Silicon Graphics Inc</FONT></P></TD> + <TD WIDTH=50%><P ALIGN=RIGHT><A HREF="http://pcp.io/"><FONT COLOR="#000060">PCP Site</FONT></A><BR>Copyright © 2012-2014 <A HREF="http://www.redhat.com/"><FONT COLOR="#000060">Red Hat</FONT></P></TD> </TR> +</TABLE> +</CENTER> +</BODY> +</HTML> diff --git a/man/html/lab.pmdas.html b/man/html/lab.pmdas.html new file mode 100644 index 0000000..a61bc1d --- /dev/null +++ b/man/html/lab.pmdas.html @@ -0,0 +1,44 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> +<HTML> +<HEAD> + <meta http-equiv="content-type" content="text/html; charset=utf-8"> + <meta http-equiv="content-style-type" content="text/css"> + <link href="pcpdoc.css" rel="stylesheet" type="text/css"> + <link href="images/pcp.ico" rel="icon" type="image/ico"> + <TITLE>Adding Metrics</TITLE> +</HEAD> +<BODY LANG="en-AU" TEXT="#000060" DIR="LTR"> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 STYLE="page-break-before: always"> + <TR> <TD WIDTH=64 HEIGHT=64><FONT COLOR="#000080"><A HREF="http://pcp.io/"><IMG SRC="images/pcpicon.png" NAME="pmcharticon" ALIGN=TOP WIDTH=64 HEIGHT=64 BORDER=0></A></FONT></TD> + <TD WIDTH=1><P> </P></TD> + <TD WIDTH=500><P VALIGN=MIDDLE ALIGN=LEFT><A HREF="index.html"><FONT COLOR="#cc0000">Home</FONT></A> · <A HREF="lab.pmchart.html"><FONT COLOR="#cc0000">Charts</FONT></A> · <A HREF="timecontrol.html"><FONT COLOR="#cc0000">Time Control</FONT></A></P></TD> + </TR> +</TABLE> +<H1 ALIGN=CENTER STYLE="margin-top: 0.48cm; margin-bottom: 0.32cm"><FONT SIZE=7>Adding Metrics</FONT></H1> +<TABLE WIDTH=15% BORDER=0 CELLPADDING=5 CELLSPACING=10 ALIGN=RIGHT> + <TR><TD BGCOLOR="#e2e2e2"><IMG SRC="images/system-search.png" WIDTH=16 HEIGHT=16 BORDER=0> <I>Tools</I><BR><PRE> +dbpmda +genpmda +python +perl +</PRE></TD></TR> +</TABLE> +<P>Introductory text. This is a placeholder. TODO... +</P> + +<P><BR></P> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 BGCOLOR="#e2e2e2"> + <TR><TD WIDTH=100% BGCOLOR="#081c59"><P ALIGN=LEFT><FONT SIZE=5 COLOR="#ffffff"><B>Next Section</B></FONT></P></TD></TR> +</TABLE> +<P>Next paragraph.</P> + +<P><BR></P> +<HR> +<CENTER> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0> + <TR> <TD WIDTH=50%><P>Copyright © 2007-2010 <A HREF="http://www.aconex.com/"><FONT COLOR="#000060">Aconex</FONT></A><BR>Copyright © 2000-2004 <A HREF="http://www.sgi.com/"><FONT COLOR="#000060">Silicon Graphics Inc</FONT></P></TD> + <TD WIDTH=50%><P ALIGN=RIGHT><A HREF="http://pcp.io/"><FONT COLOR="#000060">PCP Site</FONT></A><BR>Copyright © 2012-2014 <A HREF="http://www.redhat.com/"><FONT COLOR="#000060">Red Hat</FONT></P></TD> </TR> +</TABLE> +</CENTER> +</BODY> +</HTML> diff --git a/man/html/lab.pmie.html b/man/html/lab.pmie.html new file mode 100644 index 0000000..3967bf9 --- /dev/null +++ b/man/html/lab.pmie.html @@ -0,0 +1,550 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> +<!-- + (c) Copyright 2010 Aconex. All rights reserved. + (c) Copyright 2000-2004 Silicon Graphics Inc. All rights reserved. + 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 + http://creativecommons.org/licenses/by-sa/3.0/us/ . +--> +<HTML> +<HEAD> + <meta http-equiv="content-type" content="text/html; charset=utf-8"> + <meta http-equiv="content-style-type" content="text/css"> + <link href="pcpdoc.css" rel="stylesheet" type="text/css"> + <link href="images/pcp.ico" rel="icon" type="image/ico"> + <TITLE>Automated reasoning with pmie</TITLE> +</HEAD> +<BODY LANG="en-AU" TEXT="#000060" DIR="LTR"> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 STYLE="page-break-before: always"> + <TR> <TD WIDTH=64 HEIGHT=64><FONT COLOR="#000080"><A HREF="http://pcp.io/"><IMG SRC="images/pcpicon.png" NAME="pmcharticon" ALIGN=TOP WIDTH=64 HEIGHT=64 BORDER=0></A></FONT></TD> + <TD WIDTH=1><P> </P></TD> + <TD WIDTH=500><P VALIGN=MIDDLE ALIGN=LEFT><A HREF="index.html"><FONT COLOR="#cc0000">Home</FONT></A> · <A HREF="lab.pmchart.html"><FONT COLOR="#cc0000">Charts</FONT></A> · <A HREF="timecontrol.html"><FONT COLOR="#cc0000">Time Control</FONT></A></P></TD> + </TR> +</TABLE> +<H1 ALIGN=CENTER STYLE="margin-top: 0.48cm; margin-bottom: 0.32cm"><FONT SIZE=7> +Automated reasoning with <I>pmie</I></FONT></H1> +<TABLE WIDTH=15% BORDER=0 CELLPADDING=5 CELLSPACING=10 ALIGN=RIGHT> + <TR><TD BGCOLOR="#e2e2e2"><IMG SRC="images/system-search.png" WIDTH=16 HEIGHT=16 BORDER=0> <I>Tools</I><BR><PRE> +pmie +dkvis +pminfo +pmchart +pmdumplog +</PRE></TD></TR> +</TABLE> + +<P>For many systems, the performance data is produced in volumes and at +rates that require some sort of automated and intelligent filtering by +which the mundane data can be removed from the interesting information.</P> +<P>Once interesting information has been found, there are a variety of +actions that may be appropriate.</P> +<P>The Performance Metrics Inference Engine (<I>pmie</I>) is the tool +within PCP that is designed for automated filtering and reasoning +about performance.</P> +<P>For an explanation of Performance Co-Pilot terms and acronyms, consult +the <A HREF="glossary.html">PCP glossary</A>.</P> +<BR> +<UL> +<LI><A HREF="#basics"><I>pmie</I> basics</A> +<LI><A HREF="#repeat">Action repetition and launching arbitrary actions</A> +<LI><A HREF="#value-sets">Rule evaluation over sets of values</A> +<LI><A HREF="#predicates">Forms of <I>pmie</I> predicate</A> + <UL> + <LI><A HREF="#exist">Existential quantification</A> + <LI><A HREF="#universal">Universal quantification</A> + <LI><A HREF="#percentile">Percentile quantification</A> + <LI><A HREF="#others">Other predicates</A> + </UL> +<LI><A HREF="#expr"><I>pmie</I> expressions</A> +<LI><A HREF="#actions">Actions and parameter substitution of predicate context</A> +<LI><A HREF="#audit">Performance audit using archives</A> +<LI><A HREF="#interval">Influence of the update interval</A> +</UL> +<BR> +<P><I>pmie</I> evaluates a set of assertions against a time-series of +performance metric values collected in real-time from PMCD on one or +more hosts or from one or more PCP archives.</P> +<P>For those assertions that are found to be true, <I>pmie</I> is able +to print messages, activate alarms, write syslog entries and launch +arbitrary programs.</P> +<P>Typical <I>pmie</I> usage might include: +<UL> + <LI> monitoring for exceptional performance conditions + <LI> raising alarms + <LI> automated filtering of acceptable performance + <LI> early warning of pending performance problems + <LI> "call home" to the support center + <LI> retrospective performance audits + <LI> evaluating assertions about "before and after" + performance in the context of upgrades or system reconfiguration + <LI> hypothesis evaluation for capacity planning + <LI> as part of the <I>post mortem</I> analysis following a system failure +</UL> +</P> + +<P><BR></P> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 BGCOLOR="#e2e2e2"> + <TR><TD WIDTH=100% BGCOLOR="#081c59"><P ALIGN=LEFT><FONT SIZE=5 COLOR="#ffffff"><B><A NAME="basics"><I>pmie</I> basics</A></B></FONT></P></TD></TR> +</TABLE> +<P>The simplest rules test thresholds and are formed from expressions +involving performance metrics and constants. For example, the following +statement:</P> +<PRE> +<I> If the context switch rate exceeds 2000 switches per second</I> +<I> then activate an alarm notifier</I> +</PRE> +<P>may be translated into the following <I>pmie</I> rule:</P> +<CENTER><P ALIGN="CENTER"><IMG SRC="images/pmie_rule1.png" WIDTH="495" HEIGHT="200"></P> +</CENTER> +<P>where the "alarm" action launches an information dialog with +the specified message.</P> +<P>Other <I>pmie</I> actions are discussed later in the +<A HREF="#actions">Actions and parameter substitution of predicate context</A> section.</P> + +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0> +<TR><TD> + <TABLE WIDTH=100% BORDER=0 CELLPADDING=10 CELLSPACING=20> + <TR><TD BGCOLOR="#e2e2e2" WIDTH=50%><BR><IMG SRC="images/stepfwd_on.png" WIDTH=16 HEIGHT=16 BORDER=0> Generate alot of context switches, and watch 'em:<BR> +<PRE><B> +$ . /etc/pcp.env +$ pmie -v -c $PCP_DEMOS_DIR/pmie/pswitch.pmie & +$ pmchart -t 1sec -c $PCP_DEMOS_DIR/pmie/pswitch.view & +$ while true; do sleep 0; done & +$ jobs +[1]- Running pmie -v -c $PCP_DEMOS_DIR/pmie/pswitch.pmie & +[2]- Running pmchart -t 0.5sec -c $PCP_DEMOS_DIR/pmie/pswitch.view & +[3]+ Running while true; do sleep 0; done & +</B></PRE> +<BR> +<B>Important:</B> the above test case can be quite intrusive on low processor +count machines, so remember to terminate it when you've finished this tutorial: +<PRE><B> +$ jobs +... +[3]+ Running while true; do sleep 0; done & +$ fg %3 +</B></PRE> +</TD></TR> +</TABLE> +</TD> +<TD><IMG ALIGN=RIGHT SRC="images/cpu_pswitch.png" BORDER=0></TD> +</TR> +</TABLE> + +<P><BR></P> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 BGCOLOR="#e2e2e2"> + <TR><TD WIDTH=100% BGCOLOR="#081c59"><P ALIGN=LEFT><FONT SIZE=5 COLOR="#ffffff"><B><A NAME="repeat">Action repetition and launching arbitrary actions</A></B></FONT></P></TD></TR> +</TABLE> +<P>Sometimes it is useful for an action not to be repeated for a time. +For example, the English statement:</P> +<PRE></I> + If the context switch rate exceeds 2000 switches per second + then launch <B>top</B> in an <B>xterm</B> window + but hold off repetition of the action for 5 minutes +</I></PRE> +<P>may be translated into the following <I>pmie</I> rule:</P> +<CENTER><P ALIGN="CENTER"><IMG SRC="images/pmie_rule2.png" WIDTH="495" HEIGHT="200"></P> +</CENTER> +<P> +Note the <B><TT><FONT COLOR="#ff0000">shell</FONT></TT></B> keyword +introduces an arbitrary action in which any program can be launched.</P> + +<P><BR></P> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 BGCOLOR="#e2e2e2"> + <TR><TD WIDTH=100% BGCOLOR="#081c59"><P ALIGN=LEFT><FONT SIZE=5 COLOR="#ffffff"><B><A NAME="value-sets">Rule evaluation over sets of values</A></B></FONT></P></TD></TR> +</TABLE> +<P>Each <I>pmie</I> rule may be evaluated over a set of performance metric values.</P> +<P>Conceptually these sets of values are constructed for a single performance +metric by taking the cross product of observed values over the three +dimensions of: <B>hosts</B>, <B>instances</B> and <B>times</B>.</P> +<P>The default host is:</P> +<UL> + <LI> + the host named in the <B><TT>-h</TT></B> command line option to + <I>pmie</I>, or + <LI> + the host associated with the archive named in the first + <B><TT>-a</TT></B> command line option to <I>pmie</I>, or + <LI> + the local host if neither <B><TT>-h</TT></B> nor <B><TT>-a</TT></B> + appears on the command line. +</UL> +<P> +By default, a metric name represents the set of values formed by the +cross product of the default host for <I>pmie</I>, <B>all</B> instances +and the current time. If there is only one instance, then the set +contains a singular value.</P> +<P> +For example <B><TT>filesys.free</TT></B> is the most recent set of +values for the amount of free space on every mounted file system on the +default host, and may be represented by the shaded rectangle in the +following figure:</P> +<CENTER><P ALIGN="CENTER"><IMG SRC="images/pmie_axis1.png" WIDTH="396" HEIGHT="226"></P> +</CENTER> +<P> +One or more suffix of the form <B><TT>#<I>instance</I></TT></B> +(where <TT><I>instance</I></TT> is the external instance identifier) +after a metric name restricts the set of values on the default host +for <I>pmie</I>, to the <B>nominated</B> instances and the current time. +If <I><TT>instance</TT></I> includes any special characters then it +should be enclosed in single quotes.</P> +<P> +For example <B><TT>filesys.free #'/usr'</TT></B> is the most recent +value for the amount of free space on the <I>/usr</I> file system on the +default host, and may be represented as follows:</P> +<CENTER><P ALIGN="CENTER"><IMG SRC="images/pmie_axis2.png" WIDTH="396" HEIGHT="226"></P> +</CENTER> +<P> +One or more suffix of the form <B><TT>:<I>hostname</I></TT></B> after +a metric name changes the set of values to include <B>all</B> instances +on the <B>nominated</B> hosts, at the current time.</P> +<P> +For example <B><TT>filesys.free :otherhost</TT></B> is the most +recent set of values for the amount of free space on every mounted file +system on the host <B>otherhost</B>, and may be represented as follows:</P> +<CENTER><P ALIGN="CENTER"><IMG SRC="images/pmie_axis3.png" WIDTH="396" HEIGHT="226"></P> +</CENTER> +<P> +A suffix of the form <B><TT>@<I>N..M</I></TT></B> after a metric name +changes the set of values to be that formed by <B>all</B> instances on +the default host for <I>pmie</I>, at the sample times +<B><I><TT>N</TT></I></B>, <B><I><TT>N+1</TT></I></B>, ... +<B><I><TT>M</TT></I></B><TT> </TT><B>back</B> from the current time.</P> +<P> +And finally more than one type of suffix may be used to control enumeration +in each of the three axis directions.</P> +<P> +For example <B><TT>filesys.free #'/usr' @0..3</TT></B> refers to +the default host, restricts the instances and enumerates the time. +This may be represented as follows:</P> +<CENTER><P ALIGN="CENTER"><IMG SRC="images/pmie_axis4.png" WIDTH="396" HEIGHT="226"></P> +</CENTER> + +<P><BR></P> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 BGCOLOR="#e2e2e2"> + <TR><TD WIDTH=100% BGCOLOR="#081c59"><P ALIGN=LEFT><FONT SIZE=5 COLOR="#ffffff"><B><A NAME="predicates">Forms of <I>pmie</I> predicate</A></B></FONT></P></TD></TR> +</TABLE> +<H3><A NAME="exist">Existential quantification</A></H3> +<P> +The predicate <B><TT><FONT COLOR="#ff0000">some_inst</FONT></TT></B><TT> +<I>expr</I></TT> is true if there is some instance of a metric that +makes <I><TT>expr</TT></I> true.</P> +<P> +Existential quantification over hosts and consecutive samples is also +supported by <B><TT><FONT COLOR="#ff0000">some_host</FONT></TT></B><TT> +<I>expr</I></TT> and +<B><TT><FONT COLOR="#ff0000">some_sample</FONT></TT></B><TT> +<I>expr</I></TT>.</P> +<P> +For example, the English statement:</P> +<PRE> +<I> if some disk is doing a lot of I/O</I> +<I> then launch a visible alarm</I> +</PRE> +<P>may be translated into the following <I>pmie</I> rule:</P> +<CENTER><P ALIGN="CENTER"><IMG SRC="images/pmie_rule3.png" WIDTH="495" HEIGHT="120"></P> +</CENTER> +<BR> +<H3><A NAME="universal">Universal quantification</A></H3> +<P> +The predicate <B><TT><FONT COLOR="#ff0000">all_inst</FONT></TT></B> +<TT><I>expr</I></TT> is true if <I><TT>expr</TT></I> is true for every +instance of a metric.</P> +<P> +Universal quantification over hosts and consecutive samples is also +supported by +<B><TT><FONT COLOR="#ff0000">all_host</FONT></TT></B> <TT><I>expr</I></TT> +and <B><TT><FONT COLOR="#ff0000">all_sample</FONT></TT></B> +<TT><I>expr</I></TT>.</P> +<P> +Quantification predicates may be nested.</P> +<P> +For example, the English statement:</P> +<PRE> +<I> if for every one of the last 5 samples,</I> +<I> some disk (but not necessarily the same disk) is doing a lot of I/O</I> +<I> then launch a visible alarm</I> +</PRE> +<P>may be translated into the following <I>pmie</I> rule:</P> +<CENTER><P ALIGN="CENTER"><IMG SRC="images/pmie_rule4.png" WIDTH="540" HEIGHT="140"></P> +</CENTER> +<P>Note that reversing the nesting of the universal and existential predicates produces +a rule which has slightly different English semantics, namely:</P> +<PRE> +<I> if the same disk has been doing a lot of I/O</I> +<I> for every one of the last 5 samples,</I> +<I> then launch a visible alarm</I> +</PRE> +<CENTER><P ALIGN="CENTER"><IMG SRC="images/pmie_rule5.png" WIDTH="540" HEIGHT="140"></P> +</CENTER> +<BR> +<H3><A NAME="percentile">Percentile quantification</A></H3> +<P> +The predicate +<TT><I><FONT COLOR="#000000">N</FONT></I><B><FONT COLOR="#ff0000">%_inst</FONT></B> <I>expr</I></TT> +is true if <I><TT>expr</TT></I> is true for <I><TT>N</TT></I> percent +of the instances of a metric.</P> +<P> +Percentile quantification over hosts and consecutive samples is also +supported by +<TT><I><FONT COLOR="#000000">N</FONT></I><B><FONT COLOR="#ff0000">%_host</FONT></B> <I>expr</I></TT> and +<TT><I><FONT COLOR="#000000">N</FONT></I><B><FONT COLOR="#ff0000">%_sample</FONT></B> <I>expr</I></TT>.</P> +<P> +For example, the English phrase:</P> +<PRE> +<I> if at least 30% of the disks are doing a lot of I/O</I> +<I> then launch a visible alarm</I> +</PRE> +<P> +may be translated into the following <I>pmie</I> expression:</P> +<CENTER><P ALIGN="CENTER"><IMG SRC="images/pmie_rule3.png" WIDTH="495" HEIGHT="120"></P> +</CENTER> +<BR> +<H3><A NAME="others">Other predicates</A></H3> +<P> +Instance quantification: +<B><TT><FONT COLOR="#ff0000">match_inst</FONT></TT>, +<TT><FONT COLOR="#ff0000">nomatch_inst</FONT></TT></B></P> +<P> +Value aggregation: +<B><TT><FONT COLOR="#ff0000">avg_inst</FONT></TT>, +<TT><FONT COLOR="#ff0000">sum_inst</FONT></TT>, +<TT><FONT COLOR="#ff0000">avg_host</FONT></TT>, +<TT><FONT COLOR="#ff0000">sum_host</FONT></TT>, +<TT><FONT COLOR="#ff0000">avg_sample</FONT></TT>, +<TT><FONT COLOR="#ff0000">sum_sample</FONT></TT></B></P> +<P> +Value extrema: +<B><TT><FONT COLOR="#ff0000">min_inst</FONT></TT>, +<TT><FONT COLOR="#ff0000">max_inst</FONT></TT>, +<TT><FONT COLOR="#ff0000">min_host</FONT></TT>, +<TT><FONT COLOR="#ff0000">max_host</FONT></TT>, +<TT><FONT COLOR="#ff0000">min_sample</FONT></TT>, +<TT><FONT COLOR="#ff0000">max_sample</FONT></TT></B></P> +<P> +Value set cardinality: +<B><TT><FONT COLOR="#ff0000">count_inst</FONT></TT>, +<TT><FONT COLOR="#ff0000">count_host</FONT></TT>, +<TT><FONT COLOR="#ff0000">count_sample</FONT></TT></B></P> +<P> +Trends: +<B><TT><FONT COLOR="#ff0000">rising</FONT></TT>, +<TT><FONT COLOR="#ff0000">falling</FONT></TT>, +<TT><FONT COLOR="#ff0000">rate</FONT></TT></B></P> +<P>These predicates are discussed in depth in the <I>pmie</I> manual page.</P> + + +<P><BR></P> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 BGCOLOR="#e2e2e2"> + <TR><TD WIDTH=100% BGCOLOR="#081c59"><P ALIGN=LEFT><FONT SIZE=5 COLOR="#ffffff"><B><I><A NAME="expr">pmie</I> expressions</A></B></FONT></P></TD></TR> +</TABLE> +<P><I>pmie</I> expressions are very similar to the C programming language; +especially with regard to arithmetic, relational and Boolean operators, +and the use of parenthesis for grouping.</P> +<P>The <I>pmie</I> language allows macro definition and textual substitution +for common expressions and metric names.</P> +<PRE> + // Macro for later use ... + bc = "buffer_cache"; + + // Using the above macro + // If the buffer cache is in use (more than 50 read requests) + // with hit ratio less than 90%, then popup an alarm + $bc.getblks > 50 && $bc.getfound / $bc.getblks < 0.9 + -> alarm "poor buffer cache hit rate"; + +</PRE> +<P>All calculations are done in double precision, where default units are +<B>bytes</B>, <B>seconds</B> and <B>counts</B>. +Note that this can sometimes cause surprises:</P> +<PRE> + mem.freemem > 10; +</PRE> +<P> +will always be true, unlike</P> +<PRE> + mem.freemem > 10 Mbyte; +</PRE> +<P> +Metrics with "counter" semantics have their units, semantics +and values converted to rates. For example, the metric +<B><TT>network.interface.total.bytes</TT></B> measures the number of bytes passed +across all of the configured network interfaces. The metric is a counter and the +units are <B><TT>bytes</TT></B>. If <I>pmie</I> finds the value of +<B><TT>network.interface.total.bytes</TT></B> to be 10000 and 15000 on consecutive +fetches 5 seconds apart, then the <I>pmie</I> expression</P> +<PRE> + <B><TT>kernel.interface.total.bytes;</TT></B> +</PRE> +<P> +would have the value <B>1000</B> and the units of +<B><TT>bytes/second</TT></B>.</P> + +<P><BR></P> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 BGCOLOR="#e2e2e2"> + <TR><TD WIDTH=100% BGCOLOR="#081c59"><P ALIGN=LEFT><FONT SIZE=5 COLOR="#ffffff"><B><A NAME="actions">Actions and parameter substitution of predicate context</A></B></FONT></P></TD></TR> +</TABLE> +<P> The available <I>pmie</I> actions are:</P> +<UL> +<LI><B><TT><FONT COLOR="#ff0000">alarm</FONT></TT></B> - popup alarm notifier +<LI><B><TT><FONT COLOR="#ff0000">shell</FONT></TT></B> - launch any program +<LI><B><TT><FONT COLOR="#ff0000">syslog</FONT></TT></B> - write an entry in the system log +<LI><B><TT><FONT COLOR="#ff0000">print</FONT></TT></B> - print message to standard output +</UL> +<P>Within the arguments that follow the action keyword, parameter substitution +may be used to incorporate some context from the predicate in the arguments +to the actions. For example, when using <B><TT><FONT COLOR="#ff0000">some_host</FONT></TT></B> or <B><TT><FONT COLOR="#ff0000">some_inst</FONT></TT></B> in a predicate, it is most helpful to know "which hosts" or "which instances" +made the condition true.</P> +<P>The following substitutions are available:</P> +<UL> +<LI><B><TT><FONT COLOR="#ff0000">%h</FONT></TT></B> appearing in an action is replaced by the qualifying hosts +<LI><B><TT><FONT COLOR="#ff0000">%i</FONT></TT></B> appearing in an action is replaced by the qualifying instances +<LI><B><TT><FONT COLOR="#ff0000">%v</FONT></TT></B> appearing in an action is replaced by value of the left-most top-level +expression in the expression tree that represents the parsed condition +</UL> + +<P><BR></P> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 BGCOLOR="#e2e2e2"> + <TR><TD WIDTH=100% BGCOLOR="#081c59"><P ALIGN=LEFT><FONT SIZE=5 COLOR="#ffffff"><B><A NAME="audit">Performance audit using archives</A></B></FONT></P></TD></TR> +</TABLE> +<P> In this exercise, we shall use <I>pmie</I> to investigate performance from +a PCP archive.</P> + +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0> +<TR><TD> + <TABLE WIDTH=100% BORDER=0 CELLPADDING=10 CELLSPACING=10> + <TR><TD BGCOLOR="#e2e2e2" WIDTH=50%><BR><IMG SRC="images/stepfwd_on.png" WIDTH=16 HEIGHT=16 BORDER=0> Use <I>pmdumplog</I> to report the details of when the archive was created and from which host the archive was created:<BR> +<PRE><B> +$ . /etc/pcp.env +$ tar xzf $PCP_DEMOS_DIR/tutorials/pmie.tar.gz +$ pmdumplog -L pmie/babylon.perdisk +Log Label (Log Format Version 2) +Performance metrics from host babylon + commencing Wed Jan 25 08:17:48.460 1995 + ending Wed Jan 25 14:12:48.457 1995 +Archive timezone: PST8PDT +PID for pmlogger: 18496 +</B></PRE> +<I>Yes, PCP archives from <B>that</B> long ago still work today!</I><BR> +<BR>From running the command:<BR> +<PRE><B> +$ dkvis -a pmie/babylon.perdisk & +</B></PRE> +we can visually determine which disks and which controllers are active. +</TD> +<TD><IMG ALIGN=RIGHT SRC="images/dkvis.png" BORDER=0></TD> +</TR> +</TABLE> +<P>This is easy, which is good. +However, consider the situation where we have a large number of +separate archives, possibly collected from different machines and with +different disk configurations. We'd like to be able to quickly process +these archives, and filter out the extraneous information, to focus on +those times at which the disks were busy, how busy they were, etc.</P> + +<TABLE WIDTH=100% BORDER=0 CELLPADDING=10 CELLSPACING=20> + <TR><TD BGCOLOR="#e2e2e2" WIDTH=50%><BR><IMG SRC="images/stepfwd_on.png" WIDTH=16 HEIGHT=16 BORDER=0> Using the <I>pmie</I> configuration file in <A HREF="pmie/disk.pmie">pmie/disk.pmie</A> as a starting point, run this against the archive:<BR> +<PRE><B> +$ pmie -t 5min -a pmie/babylon.perdisk < pmie/disk.pmie +</B></PRE> +<BR> +Copy the configuration file and extend it by adding new rules to report +different messages for each of the following: +<OL> + <LI> some disk is doing more than 30 reads per second (make use of the <B><TT>disk.dev.read</TT></B> metric) + <LI> some disk is doing more than 30 writes per second (make use of the <B><TT>disk.dev.write</TT></B> metric) + <LI> some disk has a high I/O rate (consider a high I/O rate to be when the +transfers are greater than 40 per second), and where reads contribute +greater than ninety-five percent of the total transfers + <LI> some disk has a high I/O rate (as defined above) and the system's 1 +minute load average is greater than 5 (make use of the "1 +minute" instance for the <B><TT>kernel.all.load</TT></B> metric). +</OL> +<P>Use the <I>pmie/babylon.perdisk</I> archive extracted earlier to cross check your rules as you add each one.</P> +</OL> +</TD></TR> +</TABLE> + +<H4> <I>Hints:</I> </H4> +<UL> + <LI> Make sure you sample the archive every 5 minutes (<B>-t 5min</B> on the command line). + <LI> You'll need to use existential quantification (the <B>some_inst</B> keyword) in all of the rules. + <LI> When producing the final rule, start with the load average metric using the command: +<BR><BR> +<TT><B>$ pminfo -f kernel.all.load</B></TT> +<BR><BR> +Notice there are three values corresponding to the 1, 5 and 15 minute load average. +<BR> +For <I>pmie</I> the metric <TT><B>kernel.all.load</B></TT> +is a set of <B>three</B> values, one for each instance at each point +of time. To choose <B>one</B> instance append the <B><TT>#</B></TT> +qualifier to the name of the metric and the name of a particular instance, +e.g. <TT><B>kernel.all.load #'1 minute'</B></TT>. + <LI> The <I>pmie(1)</I> man page describes the <I>pmie</I> language in detail. + <LI> You may find it helpful to use <I>dkvis</I> to visually predict +when the rules should be triggered. Using the <B>PCP Archive Time Control</B> +dialog, you can position the <I>dkvis</I> display at the time where <I>pmie</I> +is reporting interesting activity. +</UL> +<P> +When all else fails, the solution is at <A HREF="pmie/answer.pmie">pmie/answer.pmie</A>.</P> + +<P><BR></P> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 BGCOLOR="#e2e2e2"> + <TR><TD WIDTH=100% BGCOLOR="#081c59"><P ALIGN=LEFT><FONT SIZE=5 COLOR="#ffffff"><B><A NAME="interval">Influence of the update interval </A></B></FONT></P></TD></TR> +</TABLE> +<P>As a final exercise, investigate the effects of using different update +intervals on the <I>pmie</I> command line (the <B>-t</B> option) with +the initial configuration file and archive from the previous exercise.</P> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=10 CELLSPACING=20> + <TR><TD BGCOLOR="#e2e2e2" WIDTH=50%><BR><IMG SRC="images/stepfwd_on.png" WIDTH=16 HEIGHT=16 BORDER=0> Try each of the following:<BR> +<PRE><B> +$ pmie -t 5min -a pmie/babylon.perdisk < pmie/disk.pmie +$ pmie -t 6min -a pmie/babylon.perdisk < pmie/disk.pmie +$ pmie -t 10min -a pmie/babylon.perdisk < pmie/disk.pmie +</B></PRE> +</TD></TR> +</TABLE> +<P>Why does the number of reported incidents decline as the rule evaluation interval increases?</P> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=10 CELLSPACING=20> + <TR><TD BGCOLOR="#e2e2e2" WIDTH=50%><BR><IMG SRC="images/stepfwd_on.png" WIDTH=16 HEIGHT=16 BORDER=0> Repeat the exercise but use <I>pmchart</I>:<BR> +<PRE><B> +$ pmchart -t 5min -a pmie/babylon.perdisk & +</B></PRE> +<BR> +Use the <B>New Chart...</B> command of the <B>File</B> menu to plot +the <B><TT>disk.dev.total</TT></B> metric for the disk <B>jag3d5</B>:<P> + <UL> + <LI> Enter the name <TT>disk.dev.total</TT> into the Metric Selection dialog. + <LI> There should be 54 instances of the metric listed. + Find the instance <B>jag3d5</B>, select it, and press OK. + </UL> +</B></PRE> +</TD></TR> +</TABLE> + +<P>Use the PCP Archive Time Control dialog to change the <B><I>Interval</I></B>.</P> +<P>By using <B>smaller</B> values of the update interval, can you +deduce the sampling rate of the data in the PCP archive?</P> + +<H4> <I>Hint:</I> </H4> +<UL> + <LI> From a PCP archive you can get a dump of the raw data and timestamps +when the data for a particular metric was collected using the command: +<BR> <BR> +<TT><B>$ pmdumplog pmie/babylon.perdisk disk.dev.total | more</B></TT> +<BR> <BR> +</UL> + +<P><BR></P> +<HR> +<CENTER> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0> + <TR> <TD WIDTH=50%><P>Copyright © 2007-2010 <A HREF="http://www.aconex.com/"><FONT COLOR="#000060">Aconex</FONT></A><BR>Copyright © 2000-2004 <A HREF="http://www.sgi.com/"><FONT COLOR="#000060">Silicon Graphics Inc</FONT></P></TD> + <TD WIDTH=50%><P ALIGN=RIGHT><A HREF="http://pcp.io/"><FONT COLOR="#000060">PCP Site</FONT></A><BR>Copyright © 2012-2014 <A HREF="http://www.redhat.com/"><FONT COLOR="#000060">Red Hat</FONT></P></TD> </TR> +</TABLE> +</CENTER> +</BODY> +</HTML> diff --git a/man/html/lab.pmieconf.html b/man/html/lab.pmieconf.html new file mode 100644 index 0000000..f8b90dd --- /dev/null +++ b/man/html/lab.pmieconf.html @@ -0,0 +1,199 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> +<!-- + (c) Copyright 2010 Aconex. All rights reserved. + (c) Copyright 2000-2004 Silicon Graphics Inc. All rights reserved. + 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 + http://creativecommons.org/licenses/by-sa/3.0/us/ . +--> +<HTML> +<HEAD> + <meta http-equiv="content-type" content="text/html; charset=utf-8"> + <meta http-equiv="content-style-type" content="text/css"> + <link href="pcpdoc.css" rel="stylesheet" type="text/css"> + <link href="images/pcp.ico" rel="icon" type="image/ico"> + <TITLE>Site rules with pmieconf</TITLE> +</HEAD> +<BODY LANG="en-AU" TEXT="#000060" DIR="LTR"> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 STYLE="page-break-before: always"> + <TR> <TD WIDTH=64 HEIGHT=64><FONT COLOR="#000080"><A HREF="http://pcp.io/"><IMG SRC="images/pcpicon.png" NAME="pmcharticon" ALIGN=TOP WIDTH=64 HEIGHT=64 BORDER=0></A></FONT></TD> + <TD WIDTH=1><P> </P></TD> + <TD WIDTH=500><P VALIGN=MIDDLE ALIGN=LEFT><A HREF="index.html"><FONT COLOR="#cc0000">Home</FONT></A> · <A HREF="lab.pmchart.html"><FONT COLOR="#cc0000">Charts</FONT></A> · <A HREF="timecontrol.html"><FONT COLOR="#cc0000">Time Control</FONT></A></P></TD> + </TR> +</TABLE> +<H1 ALIGN=CENTER STYLE="margin-top: 0.48cm; margin-bottom: 0.32cm"><FONT SIZE=7> +Site rules with <I>pmieconf</I></FONT></H1> +<TABLE WIDTH=15% BORDER=0 CELLPADDING=5 CELLSPACING=10 ALIGN=RIGHT> + <TR><TD BGCOLOR="#e2e2e2"><IMG SRC="images/system-search.png" WIDTH=16 HEIGHT=16 BORDER=0> <I>Tools</I><BR><PRE> +pmie +pmval +pmchart +pmieconf +pmdashping +</PRE></TD></TR> +</TABLE> +<P>This tutorial covers customization of <I>pmie</I> rules using +<I>pmieconf</I>. For an explanation of Performance Co-Pilot +terms and acronyms, consult the <A HREF="glossary.html">PCP glossary</A>.</P> +<UL> + <LI> + <A HREF="#start">Initial setup</A> + <LI> + <A HREF="#pmieconf">Using <I>pmieconf</I> and <I>pmie</I></A> + <LI> + <A HREF="#shping">Monitoring state with the <I>shping</I> PMDA</A> + <LI> + <A HREF="#custom">Custom site rules with <I>pmieconf</I></A> +</ul> +<P>It is advisable to first read the comprehensive introductory +<A HREF="lab.pmie.html">pmie</A> tutorial before tackling this one.</P> + +<P><BR></P> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 BGCOLOR="#e2e2e2"> + <TR><TD WIDTH=100% BGCOLOR="#081c59"><P ALIGN=LEFT><FONT SIZE=5 COLOR="#ffffff"><B><A NAME="start">Initial Setup</A></B></FONT></P></TD></TR> +</TABLE> +<P>In this exercise we create a scenario which exhibits the sort of behaviour +that might be of concern in a production environment. We'll then use +several PCP tools to detect, identify and understand the problem.</P> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0> +<TR><TD> + <TABLE WIDTH=100% BORDER=0 CELLPADDING=10 CELLSPACING=20> + <TR><TD BGCOLOR="#e2e2e2" WIDTH=50%><BR><IMG SRC="images/stepfwd_on.png" WIDTH=16 HEIGHT=16 BORDER=0> Simulate an "interesting" problem scenario:<BR> +<PRE><B> +$ while true; do sleep 0; done & +</B></PRE> +<BR> + Have a look at some of the effects it's having on the system:<BR> +<PRE><B> +$ pmchart -t 0.5sec -c CPU & +</B></PRE> +<BR> +Create a new chart showing the process context switch rate (<I>kernel.all.pswitch</I>), +adding it to your existing display.<BR><BR> +<B>Important:</B> the above test case can be quite intrusive on low processor +count machines, so remember to terminate it when you've finished this tutorial: +<PRE><B> +$ jobs +[1]- Running while true; do sleep 0; done & +[2]+ Running pmchart -t 0.5sec -c CPU & +$ fg %1 +</B></PRE> +<BR> +However, you should leave it running throughout all of the tests below. +</TD></TR> +</TABLE> +</TD> +<TD><IMG ALIGN=RIGHT SRC="images/cpu_pswitch.png" BORDER=0></TD> +</TR> +</TABLE> + +<P><BR></P> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 BGCOLOR="#e2e2e2"> + <TR><TD WIDTH=100% BGCOLOR="#081c59"><P ALIGN=LEFT><FONT SIZE=5 COLOR="#ffffff"><B><A NAME="pmieconf">Using <I>pmieconf</I> and <I>pmie</I></A></B></FONT></P></TD></TR> +</TABLE> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=10 CELLSPACING=20> + <TR><TD BGCOLOR="#e2e2e2" WIDTH=70%><BR><IMG SRC="images/stepfwd_on.png" WIDTH=16 HEIGHT=16 BORDER=0> Create your own <I>pmie</I> rules using <I>pmieconf</I>:<BR> +<PRE><B>$ pmieconf -f myrules +<I>pmieconf></I> disable all +<I>pmieconf></I> enable cpu.context_switch +<I>pmieconf></I> modify global delta "5 sec" +<I>pmieconf></I> modify global holdoff "" +<I>pmieconf></I> modify global syslog_action no +<I>pmieconf></I> modify global user_action yes +<I>pmieconf></I> quit +</B></PRE> +Determine what this command sequence has done by:<BR> +<UL> + <LI>Inspecting the created file <I>myrules</I> + <LI>Making reference to the <I>pmieconf</I> man page + <LI>Exploring other <I>pmieconf</I> commands ("help" + and "list" are useful in this context) +</UL> +Run <I>pmie</I> rules using <I>pmieconf</I>, and see if the alarm messages appear on standard output:<BR> +<PRE><B>$ pmie -c myrules +</B></PRE> +Terminate <I>pmie</I> and use the reported values from <I>pmchart</I> +to determine what the average rate of system calls is. Then +re-run <I>pmieconf</I> to adjust the threshold level up or down to alter +the behaviour of <I>pmie</I>. +Re-run <I>pmie</I>. +<PRE><B> +$ pmieconf -f myrules +<I>pmieconf></I> modify cpu.context_switch threshold 5000 <I># <-- insert suitable value here</I> +<I>pmieconf></I> quit +$ pmie -c myrules +</B></PRE> +</TD></TR> +</TABLE> + +<P><BR></P> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 BGCOLOR="#e2e2e2"> + <TR><TD WIDTH=100% BGCOLOR="#081c59"><P ALIGN=LEFT><FONT SIZE=5 COLOR="#ffffff"><B><A NAME="shping">Monitoring state with the <I>shping</I> PMDA</A></B></FONT></P></TD></TR> +</TABLE> +<H3>Installing <I>pmdashping</I> to record system state</H3> +<P>The default <I>shping</I> configuration is <I>$PCP_PMDAS_DIR/shping/sample.conf</I>. The comments explain the syntax.</P> +<P>Create a new configuration file, say <I>$PCP_PMDAS_DIR/shping/my.conf</I>, with shell tag and command of the form:</P> +<PRE><B> + no-pmie test ! -f /tmp/no-pmie +</B></PRE> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=10 CELLSPACING=20> + <TR><TD BGCOLOR="#e2e2e2" WIDTH=70%><BR><IMG SRC="images/stepfwd_on.png" WIDTH=16 HEIGHT=16 BORDER=0> Install <I>pmdashping</I>: +<PRE><B># cd $PCP_PMDAS_DIR/shping +# ./Install +</B></PRE> +Mostly take the defaults, other than specifying your own +configuration file (<I>my.conf</I>) and setting the cycle +time to 5 (seconds); don't worry about the timeout period, as +timeouts are not going to happen in this configuration of the +agent. +</TABLE> + +<H3>Monitoring <I>pmdashping</I> to observe system state</H3> +<P>In one window, use <I>pmval</I> to monitor shping.status.</P> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=10 CELLSPACING=20> + <TR><TD BGCOLOR="#e2e2e2" WIDTH=70%><BR><IMG SRC="images/stepfwd_on.png" WIDTH=16 HEIGHT=16 BORDER=0> In a command shell:<BR> +<PRE><B>$ pmval -t 5 shping.status</B></PRE> +</TD></TR> +</TABLE> +<P>In another window, first create the file <I>/tmp/no-pmie</I>, +wait ten seconds, and then remove the file. +Observe what <I>pmval</I> reports in the other window. +Terminate <I>pmval</I>. +</P> + +<P><BR></P> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 BGCOLOR="#e2e2e2"> + <TR><TD WIDTH=100% BGCOLOR="#081c59"><P ALIGN=LEFT><FONT SIZE=5 COLOR="#ffffff"><B><A NAME="custom">Custom site rules with <I>pmieconf</I></A></B></FONT></P></TD></TR> +</TABLE> +<P>Using your editor of choice, edit the <I>pmieconf</I> output +file created earlier, i.e. <I>myrules</I>. +Append a new rule at the end (after the <b>END GENERATED SECTION</b> line), +that is a <I>copy</I> of the <b>cpu.context_switch</b> rule.</P> +<P>To this new rule, add the following conjunct before the action line (containing ->), modify the message in the new rule's action to be different to the standard rule, make sure the threshold is low enough for the predicate to be true, and then save the file.</P> +<PRE><B> && shping.status #'no-pmie' == 0</B></PRE> + +<TABLE WIDTH=100% BORDER=0 CELLPADDING=10 CELLSPACING=20> + <TR><TD BGCOLOR="#e2e2e2" WIDTH=70%><BR><IMG SRC="images/stepfwd_on.png" WIDTH=16 HEIGHT=16 BORDER=0> Re-run <I>pmieconf</I> to disable the standard rule:<BR> +<PRE><B>$ pmieconf -f myrules +<I>pmieconf></I> disable cpu.context_switch +<I>pmieconf></I> quit +</B></PRE> +Inspect the re-created file <I>myrules</I>. +Check your new rule is still there and the standard rule has been removed. +</TABLE> +<P>Run <I>pmie</I> using <I>myrules</I>, and verify that your new alarm messages appear on standard output. +In another window, create the file <I>/tmp/no-pmie</I>, wait a while, then remove the file.</P> +<P>Notice there may be some delay between the creation or removal of <I>/tmp/no-pmie</I> and the change in <I>pmie</I> behaviour. Can you explain this?</P> + +<P><BR></P> +<HR> +<CENTER> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0> + <TR> <TD WIDTH=50%><P>Copyright © 2007-2010 <A HREF="http://www.aconex.com/"><FONT COLOR="#000060">Aconex</FONT></A><BR>Copyright © 2000-2004 <A HREF="http://www.sgi.com/"><FONT COLOR="#000060">Silicon Graphics Inc</FONT></P></TD> + <TD WIDTH=50%><P ALIGN=RIGHT><A HREF="http://pcp.io/"><FONT COLOR="#000060">PCP Site</FONT></A><BR>Copyright © 2012-2014 <A HREF="http://www.redhat.com/"><FONT COLOR="#000060">Red Hat</FONT></P></TD> </TR> +</TABLE> +</CENTER> +</BODY> +</HTML> diff --git a/man/html/lab.pmlogconf.html b/man/html/lab.pmlogconf.html new file mode 100644 index 0000000..6c20ae6 --- /dev/null +++ b/man/html/lab.pmlogconf.html @@ -0,0 +1,43 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> +<HTML> +<HEAD> + <meta http-equiv="content-type" content="text/html; charset=utf-8"> + <meta http-equiv="content-style-type" content="text/css"> + <link href="pcpdoc.css" rel="stylesheet" type="text/css"> + <link href="images/pcp.ico" rel="icon" type="image/ico"> + <TITLE>Configuring Logging</TITLE> +</HEAD> +<BODY LANG="en-AU" TEXT="#000060" DIR="LTR"> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 STYLE="page-break-before: always"> + <TR> <TD WIDTH=64 HEIGHT=64><FONT COLOR="#000080"><A HREF="http://pcp.io/"><IMG SRC="images/pcpicon.png" NAME="pmcharticon" ALIGN=TOP WIDTH=64 HEIGHT=64 BORDER=0></A></FONT></TD> + <TD WIDTH=1><P> </P></TD> + <TD WIDTH=500><P VALIGN=MIDDLE ALIGN=LEFT><A HREF="index.html"><FONT COLOR="#cc0000">Home</FONT></A> · <A HREF="lab.pmchart.html"><FONT COLOR="#cc0000">Charts</FONT></A> · <A HREF="timecontrol.html"><FONT COLOR="#cc0000">Time Control</FONT></A></P></TD> + </TR> +</TABLE> +<H1 ALIGN=CENTER STYLE="margin-top: 0.48cm; margin-bottom: 0.32cm"><FONT SIZE=7>Configuring Logging</FONT></H1> +<TABLE WIDTH=15% BORDER=0 CELLPADDING=5 CELLSPACING=10 ALIGN=RIGHT> + <TR><TD BGCOLOR="#e2e2e2"><IMG SRC="images/system-search.png" WIDTH=16 HEIGHT=16 BORDER=0> <I>Tools</I><BR><PRE> +pmlogconf +pmlogger +</PRE></TD></TR> +</TABLE> +<P>Introductory text. This is a placeholder. TODO... +</P> + +<P><BR></P> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 BGCOLOR="#e2e2e2"> + <TR><TD WIDTH=100% BGCOLOR="#081c59"><P ALIGN=LEFT><FONT SIZE=5 COLOR="#ffffff"><B>Next Section</B></FONT></P></TD></TR> +</TABLE> +<P>Next paragraph. +</P> + +<P><BR></P> +<HR> +<CENTER> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0> + <TR> <TD WIDTH=50%><P>Copyright © 2007-2010 <A HREF="http://www.aconex.com/"><FONT COLOR="#000060">Aconex</FONT></A><BR>Copyright © 2000-2004 <A HREF="http://www.sgi.com/"><FONT COLOR="#000060">Silicon Graphics Inc</FONT></P></TD> + <TD WIDTH=50%><P ALIGN=RIGHT><A HREF="http://pcp.io/"><FONT COLOR="#000060">PCP Site</FONT></A><BR>Copyright © 2012-2014 <A HREF="http://www.redhat.com/"><FONT COLOR="#000060">Red Hat</FONT></P></TD> </TR> +</TABLE> +</CENTER> +</BODY> +</HTML> diff --git a/man/html/lab.pmlogger.html b/man/html/lab.pmlogger.html new file mode 100644 index 0000000..c400f5a --- /dev/null +++ b/man/html/lab.pmlogger.html @@ -0,0 +1,242 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN"> +<!-- + (c) Copyright 2010 Aconex. All rights reserved. + (c) Copyright 2000-2004 Silicon Graphics Inc. All rights reserved. + 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 + http://creativecommons.org/licenses/by-sa/3.0/us/ . +--> +<HTML> +<HEAD> + <meta http-equiv="content-type" content="text/html; charset=utf-8"> + <meta http-equiv="content-style-type" content="text/css"> + <link href="pcpdoc.css" rel="stylesheet" type="text/css"> + <link href="images/pcp.ico" rel="icon" type="image/ico"> + <TITLE>Archive log management</TITLE> +</HEAD> +<BODY LANG="en-AU" TEXT="#000060" DIR="LTR"> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 STYLE="page-break-before: always"> + <TR> <TD WIDTH=64 HEIGHT=64><FONT COLOR="#000080"><A HREF="http://pcp.io/"><IMG SRC="images/pcpicon.png" NAME="pmcharticon" ALIGN=TOP WIDTH=64 HEIGHT=64 BORDER=0></A></FONT></TD> + <TD WIDTH=1><P> </P></TD> + <TD WIDTH=500><P VALIGN=MIDDLE ALIGN=LEFT><A HREF="index.html"><FONT COLOR="#cc0000">Home</FONT></A> · <A HREF="lab.pmchart.html"><FONT COLOR="#cc0000">Charts</FONT></A> · <A HREF="timecontrol.html"><FONT COLOR="#cc0000">Time Control</FONT></A></P></TD> + </TR> +</TABLE> +<H1 ALIGN=CENTER STYLE="margin-top: 0.48cm; margin-bottom: 0.32cm"><FONT SIZE=7>Archive log management</FONT></H1> +<TABLE WIDTH=15% BORDER=0 CELLPADDING=5 CELLSPACING=10 ALIGN=RIGHT> + <TR><TD BGCOLOR="#e2e2e2"><IMG SRC="images/system-search.png" WIDTH=16 HEIGHT=16 BORDER=0> <I>Tools</I><BR><PRE> +pmlc +pmafm +pmlogger +pmdumplog +mpvis +mkaf +</PRE></TD></TR> +</TABLE> +<P>This chapter of the Performance Co-Pilot tutorial covers PCP tools for +creating and managing PCP archive logs.</P> +<P>For an explanation of Performance Co-Pilot terms and acronyms, consult +the <A HREF="glossary.html">PCP glossary</A>.</P> +<UL> + <LI> + <A HREF="#overview">Overview</A> + <LI> + <A HREF="#primary">Primary Logger</A> + <LI> + <A HREF="#other">Other Logger Instances</A> + <LI> + <A HREF="#create">Creating and Replaying PCP Archive Logs</A> + <LI> + <A HREF="#folios">PCP Archive Folios</A> + <LI> + <A HREF="#control">Controlling <I>pmlogger</I></A> + <LI> + <A HREF="#manage">Management of PCP Archives</A> +</UL> + +<P><BR></P> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 BGCOLOR="#e2e2e2"> + <TR><TD WIDTH=100% BGCOLOR="#081c59"><P ALIGN=LEFT><FONT SIZE=5 COLOR="#ffffff"><B><A NAME="overview">Overview</I></A></B></FONT></P></TD></TR> +</TABLE> +<P>The Performance Co-Pilot includes many facilities for creating and +replaying archive logs that capture performance information.</P> +<P>For all PCP monitoring tools, metrics values may come from a real-time +feed (i.e. from <I>pmcd</I> on some host), or from an archive log.</P> +<P>Users have complete control of what metrics are collected, how often +and in which logs. These decisions can be changed dynamically.</P> + +<P><BR></P> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 BGCOLOR="#e2e2e2"> + <TR><TD WIDTH=100% BGCOLOR="#081c59"><P ALIGN=LEFT><FONT SIZE=5 COLOR="#ffffff"><B><A NAME="primary">Primary Logger</A></B></FONT></P></TD></TR> +</TABLE> +<P>The primary instance of the PCP archive logger (<I>pmlogger</I>) may be +started on a collector system each time <I>pmcd</I> is started.</P> +<P>This action is controlled by the chkconfig option `pmlogger'. +To turn it on, as <B>root</B> do the following:</P> +<P> +<TT># chkconfig pmlogger on</TT></BR> +<TT># /etc/init.d/pcp start</TT></P> +<P>The specification for hosts to log, and <I>pmlogger</I> options is +given in the $PCP_CONFIG_DIR/pmlogger/control</A> file.</P> +<P>This has a default entry for the local host, which specifies the metrics +to be logged, and the frequency of logging - by default, using the file +$PCP_CONFIG_DIR/pmlogger/config.default</A>.</P> + +<P><BR></P> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 BGCOLOR="#e2e2e2"> + <TR><TD WIDTH=100% BGCOLOR="#081c59"><P ALIGN=LEFT><FONT SIZE=5 COLOR="#ffffff"><B><A NAME="other">Other Logger Instances</A></B></FONT></P></TD></TR> +</TABLE> +<P>Additional instances of <I>pmlogger</I> may be started at any time, +running on either a collector system or a monitor system.</P> +<P>In all cases, each <I>pmlogger</I> instance will create an archive log +for metrics from a single collector system.</P> +<P>The initial specification of what to log is given in a configuration file; +the syntax is fully described in the <I>pmlogger</I>(1) man page.</P> + +<P><BR></P> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 BGCOLOR="#e2e2e2"> + <TR><TD WIDTH=100% BGCOLOR="#081c59"><P ALIGN=LEFT><FONT SIZE=5 COLOR="#ffffff"><B><A NAME="create">Creating and Replaying PCP Archive Logs</A></B></FONT></P></TD></TR> +</TABLE> +<P>Some configuration files are supplied, e.g. to create archive logs +suitable for the PCP visualization tools. +These may be found in the directory $PCP_CONFIG_DIR/pmlogger.</P> +<P>A simple example has been provided to illustrate the creation of an +archive log, and subsequent playback using <I>mpvis</I>. +(All of the PCP monitoring tools accept the command line arguments +<B>-a </B><TT>archivename</TT> to replay from an archive).</P> + +<TABLE WIDTH=100% BORDER=0 CELLPADDING=10 CELLSPACING=20> + <TR><TD BGCOLOR="#e2e2e2" WIDTH=70%><BR><IMG SRC="images/stepfwd_on.png" WIDTH=16 HEIGHT=16 BORDER=0> In a command shell enter:<BR> +<PRE><B> +$ source /etc/pcp.conf +$ cd /tmp +$ rm -f myarchive.* +$ $PCP_BINADM_DIR/pmlogger -T 30sec -t 1sec \ + -c $PCP_CONFIG_DIR/pmlogger/config.mpvis myarchive +$ ls myarchive.* +$ mpvis -a myarchive +</B></PRE> +</TD></TR> +</TABLE> + +<UL> + <LI> + This starts <I>pmlogger</I> with <B><I>localhost</I></B> as the default + host from which metrics will be fetched, a logging duration of + <B>30 seconds</B>, a logging interval of <B>1 second</B>, a configuration + from the $PCP_CONFIG_DIR/pmlogger/config.mpvis</A> file, and + <I>myarchive</I> as the base name of the output archive. + <LI> + Once the archive has been created, the directory listing of + <I>myarchive.*</I> shows that the archive log created by <I>pmlogger</I> + is composed of 3 files. + <LI> + When <I>mpvis</I> starts up, click the left mouse button on the + <B><I>Play</I></B> button in the <B>PCP Archive Time Control</B> + dialog. <I>mpvis</I> will start replaying values from the archive + at the same speed at which they were recorded. + <LI> + Double click the left mouse button on the <B><I>Play</I></B> button + in the <B>PCP Archive Time Control</B> dialog. <I>mpvis</I> should + now replay the values in a <I>Fast Forward</I> mode until it reaches + the end of the archive. + <LI> + Select the <B>Options->Show Bounds</B> option from the <B>PCP Archive + Time Control</B> dialog menu bar. The exposed <B>Archive Time Bounds</B> + dialog displays the bounds of the archive. Another way to look at + the bounds of the archive is by using <I>pmdumplog</I>: +<PRE> + $ pmdumplog -L myarchive +</PRE> + For more information on <I>pmdumplog</I> refer to the <I>pmdumplog</I>(1) + man page. +</UL> +</P> + +<P><BR></P> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 BGCOLOR="#e2e2e2"> + <TR><TD WIDTH=100% BGCOLOR="#081c59"><P ALIGN=LEFT><FONT SIZE=5 COLOR="#ffffff"><B><A NAME="folios">Archive Folios</A></B></FONT></P></TD></TR> +</TABLE> +<P>An archive folio is a named collection of PCP archives. +These are typically used to provide a convenient way of processing multiple, +correlated PCP archives.</P> +<P>Archive folios are created with <I>mkaf</I>.</P> +<P>The contents of an archive folio can be processed using the <I>pmafm</I> +utility.</P> +<P>A simple example has been provided to illustrate the creation and +subsequent processing of a folio.</P> + +<TABLE WIDTH=100% BORDER=0 CELLPADDING=10 CELLSPACING=20> + <TR><TD BGCOLOR="#e2e2e2" WIDTH=70%><BR><IMG SRC="images/stepfwd_on.png" WIDTH=16 HEIGHT=16 BORDER=0> In a command shell enter:<BR> +<PRE><B> +$ source /etc/pcp.conf +$ cd /tmp +$ tar xzf $PCP_DEMOS_DIR/tutorials/pmie.tar.gz +$ tar xzf $PCP_DEMOS_DIR/tutorials/cpuperf.tar.gz +$ $PCP_BINADM_DIR/mkaf pmie/babylon.perdisk.0 \ + cpuperf/babylon.percpu.0 > myfolio +$ pmafm myfolio list +$ pmafm myfolio pmdumplog -l +</B></PRE> +</TD></TR> +</TABLE> +<UL> + <LI> + The <I>mkaf</I> creates a folio called <B><I>myfolio</I></B> which + includes the archives <I>babylon.percpu</I> and <I>babylon.perdisk</I>. + Note that the archives are not changed in any way, and a new archive + is not created. + <LI> + The <I>pmafm</I> tool may now be used to perform different operations + on the folio <B><I>myfolio</I></B>, such as listing the folio contents, + or using other tools to open the archive logs contained in the folio. + If <I>pmafm</I> is given a folio name but no arguments, it will run + in interactive mode. +</UL> +</P> +<P>For more information on folios refer to the <I>mkaf</I>(1) and +<I>pmafm</I>(1) man pages.</P> + +<P><BR></P> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 BGCOLOR="#e2e2e2"> + <TR><TD WIDTH=100% BGCOLOR="#081c59"><P ALIGN=LEFT><FONT SIZE=5 COLOR="#ffffff"><B><A NAME="control">Controlling <I>pmlogger</I></A></B></FONT></P></TD></TR> +</TABLE> +<P>The <I>pmlc</I> utility may be used to interrogate any <I>pmlogger</I> +instance running either locally or remotely. Use <I>pmlc</I> to</P> +<UL> + <LI> + add or delete metrics or metric instances to be logged + <LI> + change the logging frequency for selected metrics +</UL> +<P>The line-oriented command interface to <I>pmlc</I>(1) is fully described +in the man page.</P> + +<P><BR></P> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 BGCOLOR="#e2e2e2"> + <TR><TD WIDTH=100% BGCOLOR="#081c59"><P ALIGN=LEFT><FONT SIZE=5 COLOR="#ffffff"><B><A NAME="manage">Management of PCP Archives</A></B></FONT></P></TD></TR> +</TABLE> +<P>PCP includes a suite of scripts and tools to automate the collection +and management of archives.</P> +<P>Briefly, these facilities include:</P> +<UL> + <LI>daily log rotation (<I>pmlogger_daily</I>(1)) + <LI>archive log merging (<I>pmlogextract</I>(1)) + <LI>automatic restarting of failed <I>pmlogger</I> instances + (<I>pmlogger_check</I>(1)) + <LI>creation of snapshots from archives (<I>pmsnap</I>(1)) + <LI>maintenance of archive folios for active archives + (<I>mkaf</I>(1) and <I>pmafm</I>(1)) +</UL> + +<P><BR></P> +<HR> +<CENTER> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0> + <TR> <TD WIDTH=50%><P>Copyright © 2007-2010 <A HREF="http://www.aconex.com/"><FONT COLOR="#000060">Aconex</FONT></A><BR>Copyright © 2000-2004 <A HREF="http://www.sgi.com/"><FONT COLOR="#000060">Silicon Graphics Inc</FONT></P></TD> + <TD WIDTH=50%><P ALIGN=RIGHT><A HREF="http://pcp.io/"><FONT COLOR="#000060">PCP Site</FONT></A><BR>Copyright © 2012-2014 <A HREF="http://www.redhat.com/"><FONT COLOR="#000060">Red Hat</FONT></P></TD> </TR> +</TABLE> +</CENTER> +</BODY> +</HTML> diff --git a/man/html/lab.pmview.html b/man/html/lab.pmview.html new file mode 100644 index 0000000..964cbfb --- /dev/null +++ b/man/html/lab.pmview.html @@ -0,0 +1,211 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> +<!-- + (c) Copyright 2010 Aconex. All rights reserved. + (c) Copyright 2000-2004 Silicon Graphics Inc. All rights reserved. + 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 + http://creativecommons.org/licenses/by-sa/3.0/us/ . +--> +<HTML> +<HEAD> + <meta http-equiv="content-type" content="text/html; charset=utf-8"> + <meta http-equiv="content-style-type" content="text/css"> + <link href="pcpdoc.css" rel="stylesheet" type="text/css"> + <link href="images/pcp.ico" rel="icon" type="image/ico"> + <TITLE>Performance Visualisation with pmview</TITLE> +</HEAD> +<BODY LANG="en-AU" TEXT="#000060" DIR="LTR"> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 STYLE="page-break-before: always"> + <TR> <TD WIDTH=64 HEIGHT=64><FONT COLOR="#000080"><A HREF="http://pcp.io/"><IMG SRC="images/pcpicon.png" NAME="pmcharticon" ALIGN=TOP WIDTH=64 HEIGHT=64 BORDER=0></A></FONT></TD> + <TD WIDTH=1><P> </P></TD> + <TD WIDTH=500><P VALIGN=MIDDLE ALIGN=LEFT><A HREF="index.html"><FONT COLOR="#cc0000">Home</FONT></A> · <A HREF="lab.pmchart.html"><FONT COLOR="#cc0000">Charts</FONT></A> · <A HREF="timecontrol.html"><FONT COLOR="#cc0000">Time Control</FONT></A></P></TD> + </TR> +</TABLE> +<H1 ALIGN=CENTER STYLE="margin-top: 0.48cm; margin-bottom: 0.32cm"><FONT SIZE=7>Performance Visualisation with <I>pmview</I></FONT></H1> +<TABLE WIDTH=15% BORDER=0 CELLPADDING=5 CELLSPACING=10 ALIGN=RIGHT> + <TR><TD BGCOLOR="#e2e2e2"><IMG SRC="images/system-search.png" WIDTH=16 HEIGHT=16 BORDER=0> <I>Tools</I><BR><PRE> +pmview +mpvis +osvis +dkvis +pmafm +pmtime +pmchart +</PRE></TD></TR> +</TABLE> +<P><B>Note:</B> The open source version of <I>pmview</I> is currently under development, and is <B>not</B> yet shipped as part of PCP GUI, but is available for experimental use in the development source tree.</P> +<P>Visual tools take advantage of common cognitive skills, especially for visual pattern matching and scene change discrimination. +The motivation for visualization of performance data is very similar to that used for engineering visualization, visual simulation, and database mining through visualization - visually rich representations of complex data sets are powerful aids to understanding and detection of unexpected relationships.</P> + +<UL> + <LI> + <A HREF="#realtime">Live monitoring and user interface concepts</A> + <LI> + <A HREF="#archive">Retrospective monitoring and tool drill-down</A> + <LI> + <A HREF="#vis">The "vis" tools</A> + <LI> + <A HREF="#simple">Simple scene construction</A> +</UL> +<TABLE WIDTH=50% BORDER=0 CELLPADDING=10 CELLSPACING=20> + <TR><TD BGCOLOR="#e2e2e2" WIDTH=70%><BR><IMG SRC="images/stepfwd_on.png" WIDTH=16 HEIGHT=16 BORDER=0> Extract the PCP archives and configuration files we will use in this tutorial into the current working directory: +<PRE><B> +$ . /etc/pcp.env +$ tar xzf $PCP_DEMOS_DIR/tutorials/pmview.tar.gz +</B></PRE> +</TD></TR> +</TABLE> +<P>For an explanation of Performance Co-Pilot terms and acronyms, consult +the <A HREF="glossary.html">PCP glossary</A>.</P> + +<P><BR></P> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 BGCOLOR="#e2e2e2"> + <TR><TD WIDTH=100% BGCOLOR="#081c59"><P ALIGN=LEFT><FONT SIZE=5 COLOR="#ffffff"><B><A NAME="realtime">Live monitoring and user interface concepts</A></B></FONT></P></TD></TR> +</TABLE> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0> + <TR> <TD WIDTH=568><P VALIGN=MIDDLE ALIGN=RIGHT><CENTER><BR><IMG ALIGN=RIGHT SRC="images/mpvis.png" BORDER=0></CENTER></P></TD> + <TD WIDTH=10></TD> + <TD><TABLE WIDTH=100% BORDER=0 CELLPADDING=10 CELLSPACING=20> + <TR><TD BGCOLOR="#e2e2e2" WIDTH=70%><BR><IMG SRC="images/stepfwd_on.png" WIDTH=16 HEIGHT=16 BORDER=0> The <I>mpvis</I> command monitors the CPU utilization for each CPU:<BR> +<PRE><B> +$ mpvis +</B></PRE> +<UL> + <LI> Move the cursor over each block in the scene. Take time to read the + (changed) text box above the 3D scene and understand what it is telling + you. In particular, identify the source of the metric, the name of the + metric, the instance of the metric, the current value ... can you + explain what "millisec / second" really means? + <LI> Click the left mouse over one block in the scene. How is this + different? + <LI> Click on the "Live" button or Ctrl-T or <B><I>Options -> + Show Time Control</I></B> from the menu bar. In the <B>PCP Live Time + Control</B> dialog, experiment with changing the update <B><I>Interval</I></B> + (this is the interval at which new metric values are fetched from <I>pmcd</I>). + <LI> Quit with <B><I>File -> Quit</I></B> or Ctrl-Q. +</UL> + </TD></TR> + </TABLE></TD> +</TABLE> + +<P><BR></P> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 BGCOLOR="#e2e2e2"> + <TR><TD WIDTH=100% BGCOLOR="#081c59"><P ALIGN=LEFT><FONT SIZE=5 COLOR="#ffffff"><B><A NAME="archive">Retrospective monitoring and tool drill-down</A></B></FONT></P></TD></TR> +</TABLE> + +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0> + <TR><TD><TABLE WIDTH=100% BORDER=0 CELLPADDING=10 CELLSPACING=20> + <TD BGCOLOR="#e2e2e2" WIDTH=70%><BR><IMG SRC="images/stepfwd_on.png" WIDTH=16 HEIGHT=16 BORDER=0> The <I>dkvis</I> command monitors the per-disk I/O activity:<BR> +<PRE><B> +$ dkvis -a pmie/babylon.perdisk +</B></PRE> +<UL> + <LI> In the <I>dkvis</I> window (above the top left-hand corner of the + scene) change the <B><I>Scale</I></B> to be 5 using either the + thumbwheel or the text box to the right of the thumbwheel. + <LI> In the associated <B>PCP Archive Time Control</B> dialog, changing + the update <B><I>Interval</I></B> to 2 minutes (remember to Enter + after you have changed the <B><I>Interval</I></B> text box). + <LI> Double click the <B><I>Play</I></B> button. When the replay + finished, drag the slider in the <B>PCP Archive Time Control</B> + dialog back to near the middle of the range and release the + slider. + <LI> Back in the <I>dkvis</I> window, move the cursor over each block in + the scene. Take time to read the (changed) text box above the 3D scene + and understand what it's telling you. In particular, identify the + source of the metric, the name of the metric, the instance of the + metric, the current value ... can you explain what "count / + second" really means? + <LI> Select all of the blocks for controller <B>dks1</B> (use + "Shift-select" to do multiple selections), and then <B><I>Launch -> pmchart</I></B> + from the main menu. In the pmchart window use <B><I>File -> Open View</I></B> + from the menu bar to add the <B>LoadAvg</B> view. + This is a "drill-down" example. + <LI> Use the <B>PCP Archive Time Control</B> dialog again - this time + notice that you're controlling movement through both <I>dkvis</I> + and <I>pmchart</I> using the same time control window (that's + because <I>pmchart</I> was launched from <I>dkvis</I>). + <LI> Quit from <I>dkvis</I>. Notice that <I>pmchart</I> and the <I>pmtime</I> + dialog remain. Quit from <I>pmchart</I>. +</UL> + </TD></TABLE> + </TD> + <TD WIDTH=10></TD> + <TD WIDTH=486><P VALIGN=MIDDLE ALIGN=RIGHT><CENTER><BR><IMG ALIGN=RIGHT SRC="images/dkvis.png" BORDER=0></CENTER></P></TD> + </TR> +</TABLE> + +<P><BR></P> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 BGCOLOR="#e2e2e2"> + <TR><TD WIDTH=100% BGCOLOR="#081c59"><P ALIGN=LEFT><FONT SIZE=5 COLOR="#ffffff"><B><A NAME="vis">The "vis" tools</A></B></FONT></P></TD></TR> +</TABLE> +<P> Try some of the other "vis" tools. All of these are + "front-ends" to <I>pmview</I> as shown in this diagram:</P> +<CENTER> +<IMG SRC="images/pmview.flow.png" ALIGN="MIDDLE" WIDTH="444" HEIGHT="227"> +</CENTER> + +<TABLE WIDTH=100% BORDER=0 CELLPADDING=10 CELLSPACING=20> + <TR><TD BGCOLOR="#e2e2e2" WIDTH=70%><BR><IMG SRC="images/stepfwd_on.png" WIDTH=16 HEIGHT=16 BORDER=0> In a command shell enter:<BR> +<PRE><B> +$ osvis +</B></PRE> +Move the cursor over each baseplane for more information. Now enter: +<PRE><B> +$ pmafm pmie/godzillaweb.folio replay +</B></PRE> +<I>pmafm</I> is a folio manager which allows you to work with a folio of archives for +many visualisation tools; in this case, with the folio <TT>godzillaweb</TT>. +</TD></TR> +</TABLE> + +<P><BR></P> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 BGCOLOR="#e2e2e2"> + <TR><TD WIDTH=100% BGCOLOR="#081c59"><P ALIGN=LEFT><FONT SIZE=5 COLOR="#ffffff"><B><A NAME="simple">Simple scene construction</A></B></FONT></P></TD></TR> +</TABLE> +<P>The text file <A HREF="pmview/example.view">pmview/example.view</A> +specifies a <I>pmview</I> configuration having one baseplane with +one bar containing three metrics (5, 10, and 15 minute load averages), +and separate bars for each of the disk read and write metrics. +<TABLE WIDTH=100% BORDER=0 CELLPADDING=10 CELLSPACING=20> + <TR><TD BGCOLOR="#e2e2e2" WIDTH=70%><BR><IMG SRC="images/stepfwd_on.png" WIDTH=16 HEIGHT=16 BORDER=0> To display this scene, run:<BR> +<PRE><B> +$ pmview < pmie/example.view +</B></PRE> +An a learning exercise, copy <I>example.view</I> and modify the configuration so +that instead of having the disk metrics as two separate blocks (bars), they +appear as a single stacked bar showing both metrics, one on top of the other. +</TD></TR> +</TABLE> +<H4>Hints</H4> +<UL> + <LI> + The <I>osvis</I> tool we saw earlier uses stacked bars for memory + and CPU utilization. + <LI> + The configuration generated by <B>any</B> <I>pmview </I>front-end + script can be viewed using a <B>-V</B> option to the front-end + tool, and a <B>-C</B> option means quit after generating the + configuration (do not launch <I>pmview</I>). So the following may + be helpful: + <PRE> + <I> </I><B>$</B><I> </I>osvis -V -C<I> </I> + +</PRE> + <LI> + The <I>pmview(1)</I> man page describes the <I>pmview </I>configuration + format in detail. Look for the <B><TT>_stack</TT></B> object. +</UL> + +<P><BR></P> +<HR> +<CENTER> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0> + <TR> <TD WIDTH=50%><P>Copyright © 2007-2010 <A HREF="http://www.aconex.com/"><FONT COLOR="#000060">Aconex</FONT></A><BR>Copyright © 2000-2004 <A HREF="http://www.sgi.com/"><FONT COLOR="#000060">Silicon Graphics Inc</FONT></P></TD> + <TD WIDTH=50%><P ALIGN=RIGHT><A HREF="http://pcp.io/"><FONT COLOR="#000060">PCP Site</FONT></A><BR>Copyright © 2012-2014 <A HREF="http://www.redhat.com/"><FONT COLOR="#000060">Red Hat</FONT></P></TD> </TR> +</TABLE> +</CENTER> +</BODY> +</HTML> diff --git a/man/html/lab.secure.html b/man/html/lab.secure.html new file mode 100644 index 0000000..601641b --- /dev/null +++ b/man/html/lab.secure.html @@ -0,0 +1,320 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN"> +<!-- + (c) Copyright 2013-2014 Red Hat. + 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 + http://creativecommons.org/licenses/by-sa/3.0/us/ . +--> +<HTML> +<HEAD> + <meta http-equiv="content-type" content="text/html; charset=utf-8"> + <meta http-equiv="content-style-type" content="text/css"> + <link href="pcpdoc.css" rel="stylesheet" type="text/css"> + <link href="images/pcp.ico" rel="icon" type="image/ico"> + <TITLE>Secure Connections</TITLE> +</HEAD> +<BODY LANG="en-AU" TEXT="#000060" DIR="LTR"> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 STYLE="page-break-before: always"> + <TR> <TD WIDTH=64 HEIGHT=64><FONT COLOR="#000080"><A HREF="http://pcp.io/"><IMG SRC="images/pcpicon.png" NAME="pmcharticon" ALIGN=TOP WIDTH=64 HEIGHT=64 BORDER=0></A></FONT></TD> + <TD WIDTH=1><P> </P></TD> + <TD WIDTH=500><P VALIGN=MIDDLE ALIGN=LEFT><A HREF="index.html"><FONT COLOR="#cc0000">Home</FONT></A> · <A HREF="lab.pmchart.html"><FONT COLOR="#cc0000">Charts</FONT></A> · <A HREF="timecontrol.html"><FONT COLOR="#cc0000">Time Control</FONT></A></P></TD> + </TR> +</TABLE> +<H1 ALIGN=CENTER STYLE="margin-top: 0.48cm; margin-bottom: 0.32cm"><FONT SIZE=7>Secure Connections</FONT></H1> +<TABLE WIDTH=15% BORDER=0 CELLPADDING=5 CELLSPACING=10 ALIGN=RIGHT> + <TR><TD BGCOLOR="#e2e2e2"><IMG SRC="images/system-search.png" WIDTH=16 HEIGHT=16 BORDER=0> <I>Tools</I><BR><PRE> +certutil +pmcd +pminfo +pmchart +pmproxy +</PRE></TD></TR> +</TABLE> +<P>This chapter of the Performance Co-Pilot tutorial covers setting up secure +connections between PCP collector and monitor components. +PCP network connections can be made secure against eavesdropping, data tampering +and man-in-the-middle class attacks.</P> +<P>For an explanation of Performance Co-Pilot terms and acronyms, consult +the <A HREF="glossary.html">PCP glossary</A>.</P> +<UL> + <LI> + <A HREF="#overview">Overview</A> + <LI> + <A HREF="#recipe">Enabling TLS/SSL: Steps Involved</A> + <LI> + <A HREF="#collector">Collector Setup</A> + <LI> + <A HREF="#monitor">Monitor Setup</A> +</UL> + +<P><BR></P> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 BGCOLOR="#e2e2e2"> + <TR><TD WIDTH=100% BGCOLOR="#081c59"><P ALIGN=LEFT><FONT SIZE=5 COLOR="#ffffff"><B><A NAME="overview">Overview</I></A></B></FONT></P></TD></TR> +</TABLE> +<P>The Performance Co-Pilot includes facilities for establishing secure +connections between remote collector and monitoring components.</P> +<P>All connections made to the PCP metrics collector daemon (<I>pmcd</I>) +are made using the PCP protocol, which is TCP/IP based. Traditionally, no +functionality was available to secure connections between PCP collectors and +monitors. However, as PCP evolved to be able to export sensitive information +(event trace parameters and detailed per-process statistics, for example), +it became necessary to provide safeguards against malicious behaviour.</P> +<P>The cryptographic services used to augment the PCP protocol are provided +by Network Security Services (NSS), a library implementing Transport Layer +Security (TLS) and the Secure Sockets Layer (SSL) standards, and base +cryptographic functions. NSS includes a software-based cryptographic token +which is FIPS 140-2 certified.</P> +<P>Both the <I>pmcd</I> and <I>pmproxy</I> daemons are capable of simultaneous +TLS/SSL and non-SSL communications. This means that you do not have to choose +between TLS/SSL or non-SSL communications for your PCP Collector systems; both +can be used at the same time.</P> + +<P><BR></P> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 BGCOLOR="#e2e2e2"> + <TR><TD WIDTH=100% BGCOLOR="#081c59"><P ALIGN=LEFT><FONT SIZE=5 COLOR="#ffffff"><B><A NAME="recipe">Enabling TLS/SSL: Steps Involved</A></B></FONT></P></TD></TR> +</TABLE> +<P>Before the PCP Collector system can be requested to communicate with TLS/SSL, +certificates must be properly configured on the Collector Server host.</P> +<P>This typically involves:</P> +<OL> +<LI>Obtain and install certificates for your PCP Collector systems, and +configure each system to trust the certification authority's (CA's) certificate. +Alternatively, the less secure option of generating a self-signed certificate may +be appropriate for installations where using trusted certificates is impractical. +This tutorial uses the latter approach. +<LI>Enable secure connections in the <I>pmcd</I> and <I>pmproxy</I> daemons by +configuring the system certificate database with the PCP Collector certificate. +<LI>Ensure that each user monitoring a PCP Collector system obtains and installs a +personal certificate for the tools that will communicate with that collector.<BR> +This can be done by manually updating a monitor-side certificate database, or +automatically by reviewing and accepting the certificate delivered to the monitor +tools during the first attempt to access the PCP Collector system. +</OL> +<P>The process of obtaining trusted certificates is beyond the scope of this +document, and will differ depending on whether the certificate authority is +internal or external to your organisation. +Refer to the chapter titled <I>"Requesting and Receiving Certificates"</I> in the +<A HREF="https://access.redhat.com/knowledge/docs/Red_Hat_Certificate_System/"> +Certificate System Admin Guide</A> +for details on managing trusted certificates from a certificate authority.</P> +<P>However, at a high-level: a certificate request (CR) must be generated, +then sent to the certificate authority (CA) you will be using. +The CA will generate a new trusted certificate and send it to you. +Once this certificate has been received install it in the system-wide +certificate database as described below.</P> + +<P><BR></P> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 BGCOLOR="#e2e2e2"> + <TR><TD WIDTH=100% BGCOLOR="#081c59"><P ALIGN=LEFT><FONT SIZE=5 COLOR="#ffffff"><B><A NAME="collector">Collector Setup</A></B></FONT></P></TD></TR> +</TABLE> +<P>All PCP Collector systems must have a valid certificate in order to +participate in secure PCP protocol exchanges. +Certificates are stored in a certificate database, and can be created using +<I>certutil</I> (an NSS tool).</P> +<P>In some (non-default) configurations the system certificate database +may be protected by a password. +Should you choose to select this (non-default) option, by placing the +certificate database password in a file the server can still be started +as a regular service (i.e. automatically at bootup or otherwise running +unattended). +<I> This password is stored in clear text within the password file, +so its usage represents a significant security risk.</I> +Because this password is stored in plaintext, the password file should +be owned by the user account under which the PCP Collector system runs. +By default this is the <I>"pcp"</I> user. +It must be set as read-only for this user and allow no access to others +(mode 0400).</P> + +<TABLE WIDTH=100% BORDER=0 CELLPADDING=10 CELLSPACING=20> + <TR><TD BGCOLOR="#e2e2e2" WIDTH=70%><BR><IMG SRC="images/stepfwd_on.png" WIDTH=16 HEIGHT=16 BORDER=0> Create a system-wide NSS database in a privileged (root) shell, <B><I>only if it does not exist already</I></B>:<BR> +<PRE><B> +# ls /etc/pki/nssdb +ls: cannot access /etc/pki/nssdb: No such file or directory +# mkdir -p -m 0755 /etc/pki/nssdb +# echo > /tmp/empty +# certutil -d sql:/etc/pki/nssdb -N -f /tmp/empty +# chmod 644 /etc/pki/nssdb/* +</B></PRE> +</TD></TR> +</TABLE> + +<P><I>certutil</I> is part of many modern software distributions, and can also be +downloaded from the Mozilla +<A HREF="ftp://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/">NSS</A> +project. +</P> +<P>At this stage we have a valid (possibly empty) NSS database for our collector +certificate. A list of all installed certificates can be obtained using the <B>-L</B> +option to <I>certutil</I>, as follows. + +<TABLE WIDTH=100% BORDER=0 CELLPADDING=10 CELLSPACING=20> + <TR><TD BGCOLOR="#e2e2e2" WIDTH=70%><BR><IMG SRC="images/stepfwd_on.png" WIDTH=16 HEIGHT=16 BORDER=0> List certificates in system-wide NSS database:<BR> +<PRE><B> +$ certutil -d sql:/etc/pki/nssdb -L + +Certificate Nickname Trust Attributes + SSL,S/MIME,JAR/XPI +</B><I> +[...certificates list, possibly none at this stage...]</I> +</PRE> +</TD></TR> +</TABLE> + +<P>Certificates should now be requested from your local trusted certificate authority (CA). +Alternatively, it is possible to generate a "self-signed" certificate as follows, +using the <B>-x</B> option to <I>certutil</I>. + +<TABLE WIDTH=100% BORDER=0 CELLPADDING=10 CELLSPACING=20> + <TR><TD BGCOLOR="#e2e2e2" WIDTH=70%><BR><IMG SRC="images/stepfwd_on.png" WIDTH=16 HEIGHT=16 BORDER=0> After customising the certificate subject names (<B>-s</B> and <B>-8</B> options below), in a privileged shell enter:<BR> +<PRE><B> +# certutil -d sql:/etc/pki/nssdb -S -x \ + -n "<FONT COLOR=#000000">Local CA certificate</FONT>" -s "cn=<FONT COLOR="#000000">Local PCP Installation</FONT>, dc=<FONT COLOR="#cc0000">YOUR</FONT>,dc=<FONT COLOR="#cc0000">DOMAIN</FONT>,dc=<FONT COLOR="#cc0000">NAME</FONT>" \ + -t "CT,," -v 120 + +# certutil -d sql:/etc/pki/nssdb -S \ + -c "<FONT COLOR=#000000">Local CA certificate</FONT>" \ + -n "PCP Collector certificate" -s "cn=PCP Collector" -8 "<FONT COLOR="#cc0000">YOUR.HOST.NAME,ALT.DNS.NAME,...</FONT>" \ + -t "P,," -v 120 +</B></PRE> +</TD></TR> +</TABLE> +</P> +<P>Note: You <B>must</B> customise the red parameters above in upper-case. +If you are not using self-signed certificates, you will also need to +customise the black parameters above to match certificate details provided +by your CA. Finally, you may also wish to change the <B>-v</B> setting, +which sets the certificate expiry timeframe. <I>certutil</I> defaults +to 3 months, the example above sets expiry in 10 years (120 months). +</P> +<P>At this stage, attempts to restart the PCP Collector infrastructure will +begin to take notice of the new contents of the certificate database. +If we earlier chose to create the system-wide database in the non-default +configuration of having a password, we must now configure <I>pmcd</I> +and <I>pmproxy</I> to make use of it. +This configuration must be performed in the <I>$PCP_PMCDOPTIONS_PATH</I> and +<I>$PCP_PMPROXYOPTIONS_PATH</I> files, as recorded in <I>/etc/pcp.conf</I>, +using the <B>-P <path></B> option to these daemons. +Detailed diagnostics are available in the daemon log files, +located below <I>$PCP_LOG_DIR</I>. +</P> + +<P><BR></P> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 BGCOLOR="#e2e2e2"> + <TR><TD WIDTH=100% BGCOLOR="#081c59"><P ALIGN=LEFT><FONT SIZE=5 COLOR="#ffffff"><B><A NAME="monitor">Monitor Setup</A></B></FONT></P></TD></TR> +</TABLE> +<P>PCP Monitoring (client) tools require a trusted certificate to validate +the server in a TLS/SSL connection. +This certificate can be installed beforehand or can be delivered via the +TLS/SSL connection exchange. +In the latter situation, the user is prompted as to whether the +certificate is to be trusted (see example below).</P> +<P>Once certificates are in place, we are ready to attempt to establish secure +connections between remote PCP Monitor and Collector hosts. +This can be achieved by specifically requesting a secure connection for individual +host connections, in tools that support this explictly (e.g. <I>pmchart</I> below). +Alternatively, an environment variable can be set to request that all client +connections within that shell environment be made securely. +This environment variable can have the value <I><B>enforce</B></I> meaning "all +connections must be secure, fail if this cannot be achieved", +or <I><B>relaxed</B></I> meaning "establish secure connections only for remote +collector systems that are configured, fallback to insecure connections if not". +</P> + +<P>Using the approach of certificate delivery via the TLS/SSL protocol, the database +and certificate will be automatically setup in the correct location on your behalf. +<TABLE WIDTH=100% BORDER=0 CELLPADDING=10 CELLSPACING=20> + <TR><TD BGCOLOR="#e2e2e2" WIDTH=70%><BR><IMG SRC="images/stepfwd_on.png" WIDTH=16 HEIGHT=16 BORDER=0> To establish a secure connection, in a shell enter:<BR> +<PRE><B> +$ export PCP_SECURE_SOCKETS=enforce +$ pminfo -h <FONT COLOR="#cc0000">YOUR.HOST.NAME</FONT> -f kernel.all.load +WARNING: issuer of certificate received from host <FONT COLOR="#000000">YOUR.HOST.NAME</FONT> is not trusted. +SHA1 fingerprint is <FONT COLOR="#000000">34:92:D2:DC:DE:28:3A:2D:DD:B9:1A:6C:C9:51:1E:B8:FA:CE:63:51</FONT> +Do you want to accept and save this certificate locally anyway (y/n)? <FONT COLOR="#000000">y</FONT> + +kernel.all.load + inst [1 or "1 minute"] value <FONT COLOR="#000000">1.26</FONT> + inst [5 or "5 minute"] value <FONT COLOR="#000000">1.29</FONT> + inst [15 or "15 minute"] value <FONT COLOR="#000000">1.28</FONT> +</B></PRE> +</TD></TR> +</TABLE> +</P> +<P>At any time, you can query the certificates you have installed locally +for remote collector hosts. +<TABLE WIDTH=100% BORDER=0 CELLPADDING=10 CELLSPACING=20> + <TR><TD BGCOLOR="#e2e2e2" WIDTH=70%><BR><IMG SRC="images/stepfwd_on.png" WIDTH=16 HEIGHT=16 BORDER=0> To list the locally installed server certificates, in a shell enter:<BR> +<PRE><B> +$ certutil -d sql:$HOME/.pki/nssdb -L + +Certificate Nickname Trust Attributes + SSL,S/MIME,JAR/XPI + +PCP Collector certificate Pu,u,u +PCP Collector certificate Pu,u,u +PCP Collector certificate Pu,u,u +PCP Collector certificate Pu,u,u + +$ certutil -d sql:$HOME/.pki/nssdb -L -n 'PCP Collector certificate' | grep 'DNS name:' +</B></PRE> +</TD></TR> +</TABLE> +When listing by nickname, this provides a detailed certificate list, so using an +output filter as shown above can be handy to report only the hostnames. +</P> +<BR> +<P>Alternatively, using the manual approach, first use <I>certutil</I> to ensure +a user database exists, then export either the CA or the collector certificate +in ASCII format for the PCP Collector system we wish to monitor and +finally import it into the user database. +<TABLE WIDTH=100% BORDER=0 CELLPADDING=10 CELLSPACING=20> + <TR><TD BGCOLOR="#e2e2e2" WIDTH=70%><BR><IMG SRC="images/stepfwd_on.png" WIDTH=16 HEIGHT=16 BORDER=0> Step 1: Create a local user NSS database in a command shell, <B><I>only if it does not exist already</I></B>:<BR> +<PRE><B> +$ ls $HOME/.pki/nssdb +ls: cannot access .pki/nssdb: No such file or directory +$ mkdir -p -m 0755 $HOME/.pki/nssdb +$ test -f /tmp/empty || echo > /tmp/empty +$ certutil -d sql:$HOME/.pki/nssdb -N -f /tmp/empty +</B></PRE> +</TD></TR> + <TR><TD BGCOLOR="#e2e2e2" WIDTH=70%><BR><IMG SRC="images/stepfwd_on.png" WIDTH=16 HEIGHT=16 BORDER=0> Step 2: To export the <I>collector</I> system CA certificate as ASCII, in a shell enter:<BR> +<PRE><B> +$ certutil -d sql:/etc/pki/nssdb -L -n "Local CA certificate" -a > /tmp/ca-certificate.asc +</B></PRE> +</TD></TR> + <TR><TD BGCOLOR="#e2e2e2" WIDTH=70%><BR><IMG SRC="images/stepfwd_on.png" WIDTH=16 HEIGHT=16 BORDER=0> Step 3: To import the certificate as ASCII on a <I>monitor</I> system, in a shell enter:<BR> +<PRE><B> +$ certutil -d sql:$HOME/.pki/nssdb -A -n "Local CA certificate" -t "CT,," -a -i /tmp/ca-certificate.asc +</B></PRE> +</TD></TR> +</TABLE> +Note: Cunning use of this trusted certificate could be used as the root certificate +for many hosts in an environment, and a single certificate could then be installed +on a monitor system allowing access to a group of hosts. +<BR> +</P> +<BR> +<P ALIGN=LEFT><FONT SIZE=4><B>Graphical Monitor Tools</B></FONT> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 STYLE="page-break-before: always"> + <TR><TD WIDTH=500><P VALIGN=MIDDLE ALIGN=><CENTER><BR><IMG ALIGN=MIDDLE SRC="images/pmchart_add_host_secure.png" BORDER=0></CENTER></P></TD> + <TD><P>In the PCP strip chart utility <I>pmchart</I> from version 1.5.7 onward, secure connections can be established using the "Add Host" dialog. This can be accessed via the "New Chart" or "Open View" menu entries.<UL> + <LI>Specify the name of the PCP Collector system where <I>pmcd</I> is running. + <LI>Select the "Secure" check box. + <LI>Press "OK" to establish a new secure connection to the host. + </UL> + Note that it is not necessary to use the PCP_SECURE_SOCKETS environment variable described above with <I>pmchart</I>. However, if it is used, secure connections will become the default mode for all connections established by <I>pmchart</I> too. + </P></TD> + </TR> +</TABLE> +</P> +<P><BR></P> +<HR> +<CENTER> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0> + <TR> <TD WIDTH=50%><P>Copyright © 2007-2010 <A HREF="http://www.aconex.com/"><FONT COLOR="#000060">Aconex</FONT></A><BR>Copyright © 2000-2004 <A HREF="http://www.sgi.com/"><FONT COLOR="#000060">Silicon Graphics Inc</FONT></P></TD> + <TD WIDTH=50%><P ALIGN=RIGHT><A HREF="http://pcp.io/"><FONT COLOR="#000060">PCP Site</FONT></A><BR>Copyright © 2012-2014 <A HREF="http://www.redhat.com/"><FONT COLOR="#000060">Red Hat</FONT></P></TD> </TR> +</TABLE> +</CENTER> +</BODY> +</HTML> diff --git a/man/html/lab.trace.html b/man/html/lab.trace.html new file mode 100644 index 0000000..536217b --- /dev/null +++ b/man/html/lab.trace.html @@ -0,0 +1,555 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> +<!-- + (c) Copyright 2010 Aconex. All rights reserved. + (c) Copyright 2000-2004 Silicon Graphics Inc. All rights reserved. + 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 + http://creativecommons.org/licenses/by-sa/3.0/us/ . +--> +<HTML> +<HEAD> + <meta http-equiv="content-type" content="text/html; charset=utf-8"> + <meta http-equiv="content-style-type" content="text/css"> + <link href="pcpdoc.css" rel="stylesheet" type="text/css"> + <link href="images/pcp.ico" rel="icon" type="image/ico"> + <TITLE>Trace Agent</TITLE> +</HEAD> +<BODY LANG="en-AU" TEXT="#000060" DIR="LTR"> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 STYLE="page-break-before: always"> + <TR> <TD WIDTH=64 HEIGHT=64><FONT COLOR="#000080"><A HREF="http://pcp.io/"><IMG SRC="images/pcpicon.png" NAME="pmcharticon" ALIGN=TOP WIDTH=64 HEIGHT=64 BORDER=0></A></FONT></TD> + <TD WIDTH=1><P> </P></TD> + <TD WIDTH=500><P VALIGN=MIDDLE ALIGN=LEFT><A HREF="index.html"><FONT COLOR="#cc0000">Home</FONT></A> · <A HREF="lab.pmchart.html"><FONT COLOR="#cc0000">Charts</FONT></A> · <A HREF="timecontrol.html"><FONT COLOR="#cc0000">Time Control</FONT></A></P></TD> + </TR> +</TABLE> +<H1 ALIGN=CENTER STYLE="margin-top: 0.48cm; margin-bottom: 0.32cm"><FONT SIZE=7>Trace Agent</FONT></H1> +<TABLE WIDTH=15% BORDER=0 CELLPADDING=5 CELLSPACING=10 ALIGN=RIGHT> + <TR><TD BGCOLOR="#e2e2e2"><IMG SRC="images/system-search.png" WIDTH=16 HEIGHT=16 BORDER=0> <I>Tools</I><BR><PRE> +pmdatrace +pmtrace +pminfo +</PRE></TD></TR> +</TABLE> +<P>This chapter of the Performance Co-Pilot tutorial discusses application +instrumentation using the <B>trace</B> PMDA (Performance Metrics Domain Agent). +The trace agent has similar aims to the <A HREF="lab.mmapvalues.html">Memory +Mapped Values</A> (MMV) agent, in that both interfaces for application instrumentation. +The main differences are:</P> +<UL> + <LI> The <I>trace</I> PMDA is a predecessor to <I>MMV</I>, and it is expected + that most instrumented applications would use <I>MMV</I>. + <LI> The <I>trace</I> interface uses sockets for communication between + applications and agent, <I>MMV</I> uses memory mapped files. This + is heavier weight but allows for instrumentation to be sent between hosts, + optionally. + <LI> <I>MMV</I> allows the application to completely specify every aspect of + each metric it exports, the <I>trace</I> agent has a small number of metrics + with relatively fixed metadata, and each applications instrumentation is + exported as an instance of these fixed metrics. + <LI> This fixed nature of the <I>trace</I> metrics caters for existance of the + program <I>pmtrace</I> allowing simple instrumentation from the shell. +</UL> + +<P>For an explanation of Performance Co-Pilot terms and acronyms, consult +the <A HREF="glossary.html">PCP glossary</A>.</P> +<UL> + <LI> <A HREF="#overview">Overview</A> + <LI> <A HREF="#design">Trace Agent Design</A> + <UL> + <LI> Application Interaction + <LI> Sampling Techniques + <LI> Configuring the Trace Agent + </UL> + <LI> <A HREF="#traceapi">The Trace API</A> + <UL> + <LI> Transactions + <LI> Point Tracing + <LI> Observations/Counters + <LI> Configuring the Trace library + </UL> + <LI> <A HREF="#export">Instrumenting Applications to Export Performance Data</A> +</UL> + +<P><BR></P> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 BGCOLOR="#e2e2e2"> + <TR><TD WIDTH=100% BGCOLOR="#081c59"><P ALIGN=LEFT><FONT SIZE=5 COLOR="#ffffff"><B><A NAME="overview">Overview</A></B></FONT></P></TD></TR> +</TABLE> +<P> This document provides an introduction to the design of the <B>trace</B> +agent, in an effort to explain how to configure the agent optimally for +a particular problem domain. This will be most useful as a supplement +to the functional coverage which the manual pages provide to both the +agent and the library interfaces.</P> +<P> Details of the use of the <B>trace</B> agent, and the associated +library (<I>libpcp_trace</I>) for instrumenting applications, are also +discussed.</P> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=10 CELLSPACING=20> + <TR><TD BGCOLOR="#e2e2e2" WIDTH=70%><BR><IMG SRC="images/stepfwd_on.png" WIDTH=16 HEIGHT=16 BORDER=0> In a command shell enter:<BR> +<PRE><B> +# . /etc/pcp.conf +# cd $PCP_PMDAS_DIR/trace +# ./Install +</PRE></B> +Export a value, from the shell using: +<PRE><B> +$ pmtrace -v 100 "database-users" +$ pminfo -f trace +</PRE></B> +</TD></TR> +</TABLE> + +<P><BR></P> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 BGCOLOR="#e2e2e2"> + <TR><TD WIDTH=100% BGCOLOR="#081c59"><P ALIGN=LEFT><FONT SIZE=5 COLOR="#ffffff"><B><A NAME="design">Trace Agent Design</A></B></FONT></P></TD></TR> +</TABLE> +<H4>Application Interaction</H4> +<P> The diagram below describes the general state maintained within the <B>trace</B> +agent. Applications which are linked with the <I>libpcp_trace</I> + library make calls through the trace Applications Programmer Interface +(API), resulting in inter-process communication of trace data between +the application and the <B>trace</B> agent. This data consists of an +identification tag, and the performance data associated with that +particular tag. The <B>trace</B> agent aggregates the incoming +information and periodically updates the exported summary information +to describe activity in the recent past.</P> +<P> +As each PDU (Protocol Data Unit) is received, its data is stored in the +current <I>working buffer</I>, and 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 which has +arrived since the previous time interval elapsed, and is discussed in +greater detail in the <B>Rolling Window Sampling Technique</B> section +below.</P> +<CENTER><P ALIGN="CENTER"> +<IMG SRC="images/trace_1.png" ALIGN="MIDDLE" WIDTH="511" HEIGHT="332"></P> +</CENTER><P> +<BR> +</P> +<H4> +Sampling Techniques</H4> +<P> +The <B>trace</B> agent employs a <B>rolling window periodic sampling</B> + technique. The recency of the data exported by the agent is determined +by its arrival time at the agent in conjunction with the length of the +sampling period being maintained by the <B>trace</B> agent. Through the +use of rolling window sampling, the <B>trace</B> agent is able to +present a more accurate representation of the available trace data at +any given time.</P> +<P> +The metrics affected by the agents rolling window sampling technique +are:</P> +<UL> + <LI> + <B><TT>trace.transact.rate</TT></B> + <LI> + <B><TT>trace.transact.ave_time</TT></B> + <LI> + <B><TT>trace.transact.min_time</TT></B> + <LI> + <B><TT>trace.transact.max_time</TT></B> + <LI> + <B><TT>trace.point.rate</TT></B> + <LI> + <B><TT>trace.observe.rate</TT></B> + <LI> + <B><TT>trace.counter.rate</TT></B> +</UL> +<P> +The remaining metrics are either global counters, control metrics, or +the last seen observation/counter value. All metrics exported by the <B>trace</B> +agent are explained in detail in the API section below.</P> +<H5> +Simple periodic sampling</H5> +<P> +This technique uses a single historical buffer to store the history of +events which 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 (ready to hold new +events from the sampling interval now starting).</P> +<H5> +Rolling window periodic sampling</H5> +<P> +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 this.</P> +<P> +At a specified interval (which is a function of the number of +historical buffers maintained) the current working buffer and the +accumulated data which it holds is moved into the set of historical +buffers, and a new working buffer is used.</P> +<P> +The primary advantage of the rolling window approach is that at the +point where data is actually exported, the data which is exported has a +higher probability of reflecting a more recent sampling period than the +data exported using simple periodic sampling.</P> +<CENTER><P ALIGN="CENTER"> +<IMG SRC="images/trace_buffer.png" ALIGN="MIDDLE" WIDTH="425" + HEIGHT="391"></P> +</CENTER><P> +<BR> +</P> +<P> +The data collected over each sample duration and exported using the +rolling window technique provides a more up-to-date representation of +the activity during the most recently completed sample duration.</P> +<P> +The <B>trace</B> agent allows the length of the sample duration to be +configured, as well as the number of historical buffers which are to be +maintained. The rolling window is implemented in the <B>trace</B> agent +as a ring buffer (as shown earlier in the "Trace agent +Overview" diagram), such that 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.</P> +<H5> +Example of window periodic sampling </H5> +<P> +Consider the scenario where one wants to know the rate of transactions +over the last 10 seconds. To do this one would set the sampling rate +for the trace agent to be 10 seconds and would fetch the metric <B><TT>trace.transact.rate</TT></B>. +So if in the last 10 seconds we had 8 transactions take place then we +would have a transaction rate of 8/10 or 0.8 transactions per second.</P> +<P> +As mentioned above, the trace agent does not actually do this. It +instead does its calculations automatically at a subinterval of the +sampling interval. Consider the example above with a calculation +subinterval of 2 seconds. Please refer to the bar chart below. At time +13.5 secs the user requests the transaction rate and is told it is has +a value of 0.7 transactions per second. In actual fact, the transaction +rate was 0.8 but the agent has done its calculations on the sampling +interval from 2 secs to 12 secs and not from 3.5 secs to 13.5 secs. +Every 2 seconds it will do the metrics calculations on the last 10 +seconds at that time. It does this for efficiency and so it is not +driven each time to do a calculation for a fetch request.</P> +<CENTER><P ALIGN="CENTER"> +<IMG SRC="images/trace_example.png" ALIGN="MIDDLE"></P> +</CENTER><P> +<BR> +</P> +<H4> +Configuring the Trace agent</H4> +<P> +The <B>trace</B> agent is configurable primarily through command line +options. The list of command line options presented below is not +exhaustive, but covers those options which are particularly relevant to +tuning the manner in which performance data is collected.</P> +<H5> +Options: </H5> +<DL> + <DT> + <B>Access Controls</B> + <DD> + host-based access control is offered by the <B>trace</B> agent, + allowing and disallowing 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 + <DT> + <B>Sample Duration</B> + <DD> + interval over which metrics are to be maintained before being + discarded. + <DT> + <B>Number of Historical Buffers</B> + <DD> + the data maintained for the sample duration is held in a number of + internal buffers within the <B>trace</B> agent. This number is + configurable, allowing the rolling window effect to be tuned (within + the sample duration) + <DT> + <B>Observation/Counter Metric Units</B> + <DD> + since the data being exported by the <B><TT>trace.observe.value</TT></B> + and <B><TT>trace.counter.value</TT></B> metrics is user-defined, + the <B>trace</B> agent by default exports these metrics with a type + of "none". A framework is provided allowing this to be made + more specific (bytes per second, for example), allowing the exported + values to be plotted along with other performance metrics of similar + units by tools like <I>pmchart</I>) + <DT> + <B>Instance Domain Refresh</B> + <DD> + the set of instances exported for each of the trace metrics can be + cleared through the storable <B><TT>trace.control.reset</TT></B> + metric. +</DL> + +<P><BR></P> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 BGCOLOR="#e2e2e2"> + <TR><TD WIDTH=100% BGCOLOR="#081c59"><P ALIGN=LEFT><FONT SIZE=5 COLOR="#ffffff"><B><A NAME="traceapi">The Trace API</A></B></FONT></P></TD></TR> +</TABLE> +<P>The <I>libpcp_trace</I> Applications Programmer Interface (API) may be +called from C, C++, Fortran, and Java. Each language has access to the +complete set of functionality offered by <I>libpcp_trace</I>, although +in some cases the calling conventions differ slightly between +languages. An overview of each of the different tracing mechanisms +offered by the API follows, as well as an explanation of their mappings +to the actual performance metrics exported by the <B>trace</B> agent.</P> +<H4>Transactions </H4> +<P>Paired calls to the <I>pmtracebegin</I>(3) and <I>pmtraceend</I>(3) API +functions will result in transaction data being sent to the agent with +a measure of the time interval between the two calls (which is assumed +to be the transaction service time). Using the <I>pmtraceabort</I>(3) +call causes data for that particular transaction to be discarded. +Transaction data is exported through the <B>trace</B> agents <B><TT>trace.transact</TT></B> + metrics.</P> +<DL> + <DT> + <B><TT>trace.transact.count</TT></B> + <DD> + running count for each transaction type seen since the trace agent started + <DT> + <B><TT>trace.transact.rate</TT></B> + <DD> + the average rate at which each transaction type is completed, + calculated over the last sample duration + <DT> + <B><TT>trace.transact.ave_time</TT></B> + <DD> + the average service time per transaction type, calculated over the last + sample duration + <DT> + <B><TT>trace.transact.min_time</TT></B> + <DD> + minimum service time per transaction type within the last sample + duration + <DT> + <B><TT>trace.transact.max_time</TT></B> + <DD> + maximum service time per transaction type within the last sample + duration + <DT> + <B><TT>trace.transact.total_time</TT></B> + <DD> + cumulative time spent processing each transaction since the <B>trace</B> + agent started running +</DL> +<H4> +Point tracing </H4> +<P> +Point tracing allows the application programmer to export metrics +related to salient events. The <I>pmtracepoint</I>(3) function is most +useful when start and end points are not well defined, eg. 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 the desired instrumentation is akin to event rates rather than event +service times. This data is exported through the <B><TT>trace.point</TT></B> + metrics.</P> +<DL> + <DT> + <B><TT>trace.point.count</TT></B> + <DD> + running count of point observations for each tag seen since the <B>trace</B> + agent started + <DT> + <B><TT>trace.point.rate</TT></B> + <DD> + the average rate at which observation points occur for each tag, within + the last sample duration +</DL> +<H4> +Observations/Counters</H4> +<P> +The <I>pmtraceobs</I>(3) and <I>pmtracecounter</I>(3) functions have +similar semantics to <I>pmtracepoint</I>(3), but also allow an +arbitrary numeric value to be passed to the <B>trace</B> agent. The most +recent value for each tag is then immediately available from the agent. +Observation and counter data is exported through the <B><TT>trace.observe</TT></B> + and <B><TT>trace.counter</TT></B> metrics, and these differ only in +the PMAPI semantics associated with their respective value metrics (the +PMAPI semantics for these two metrics is "instantaneous" or +"counter" - refer to the PMAPI(3) manual page for details on +PMAPI metric semantics).</P> +<DL> + <DT> + <B><TT>trace.observe.count, trace.counter.count</TT></B> + <DD> + running count of observations/counters seen since the <B>trace</B> + agent started + <DT> + <B><TT>trace.observe.rate, trace.counter.rate</TT></B> + <DD> + the average rate at which observations/counters for each tag occur, + calculated over the last sample duration + <DT> + <B><TT>trace.observe.value, trace.counter.value</TT></B> + <DD> + the numeric value associated with the observation/counter last seen by + the agent +</DL> +<H4> +Configuring the Trace library </H4> +<P> +The trace library is configurable through the use of environment +variables, as well as through state flags, which provide diagnostic +output and enable or disable the configurable functionality within the +library.</P> +<H5> +Environment variables: </H5> +<DL> + <DT> + <B><TT>PCP_TRACE_HOST</TT></B> + <DD> + the name of the host where the <B>trace</B> agent is running + <DT> + <B><TT>PCP_TRACE_PORT</TT></B> + <DD> + TCP/IP port number on which the <B>trace</B> agent is accepting + client connections + <DT> + <B><TT>PCP_TRACE_TIMEOUT</TT></B> + <DD> + number to seconds to wait until assuming that the initial connection is + not going to be made, and timeout is to occur (the default is three + seconds) + <DT> + <B><TT>PCP_TRACE_REQTIMEOUT</TT></B> + <DD> + number of seconds to allow before timing out on awaiting + acknowledgement from the <B>trace</B> agent after trace data has + been sent to it. This variable has no effect in the asynchronous trace + protocol (refer to <B><TT>PMTRACE_STATE_ASYNC</TT></B> under `State + Flags', below) + <DT> + <B><TT>PCP_TRACE_RECONNECT</TT></B> + <DD> + a list of values which represents the backoff approach to be taken by + the <I>libpcp_trace</I> library routines when attempting to + reconnect to the <B>trace</B> agent 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 then used for all + subsequent reconnection attempts. +</DL> +<H5> +State flags: </H5> +<P> +The following flags can be used to customize the operation of the <I>libpcp_trace</I> + routines. These are registered through the <I>pmtracestate</I>(3) +call, and can be set either individually or together.</P> +<DL> + <DT> + <B><TT>PMTRACE_STATE_NONE</TT></B> + <DD> + the default - no state flags have been set - the fault-tolerant, + synchronous protocol is used for communicating with the agent, and no + diagnostic messages are displayed by the <I>libpcp_trace</I> + routines <B><TT>PMTRACE_STATE_API</TT></B> + <DD> + high-level diagnostics - simply displays entry into each of the API + routines + <DT> + <B><TT>PMTRACE_STATE_COMMS</TT></B> + <DD> + diagnostic messages related to establishing and maintaining the + communication channel between application and agent + <DT> + <B><TT>PMTRACE_STATE_PDU</TT></B> + <DD> + the low-level details of the trace PDUs (Protocol Data Units) is + displayed as each PDU is transmitted or received + <DT> + <B><TT>PMTRACE_STATE_PDUBUF</TT></B> + <DD> + the full contents of the PDU buffers are dumped, as PDUs are + transmitted and received + <DT> + <B><TT>PMTRACE_STATE_NOAGENT</TT></B> + <DD> + if set, causes inter-process communication between the instrumented + application and the <B>trace</B> agent to be skipped - this is + intended as a debugging aid for applications using <I>libpcp_trace</I> + + <DT> + <B><TT>PMTRACE_STATE_ASYNC</TT></B> + <DD> + flag which enables the asynchronous trace protocol, such that the + application does not block awaiting acknowledgement PDUs from the agent. + This must be set before using the other <I>libpcp_trace</I> entry + points in order for it to be effective. +</DL> + +<P><BR></P> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 BGCOLOR="#e2e2e2"> + <TR><TD WIDTH=100% BGCOLOR="#081c59"><P ALIGN=LEFT><FONT SIZE=5 COLOR="#ffffff"><B><A NAME="export">Instrumenting Applications to Export Performance Data</A></B></FONT></P></TD></TR> +</TABLE> +<P>The <I>libpcp_trace</I> library is designed to encourage application +developers (Independent Software Vendors and end-user customers) to +embed calls in their code that enable application performance data to +be exported. When combined with system-level performance data this +allows total performance and resource demands of an application to be +correlated with application activity.</P> +<P>Some illustrative application performance metrics might be:</P> +<UL> + <LI> + computation state (especially for codes with major shifts in resource + demands between phases of their execution) + <LI> + problem size and parameters, e.g. degree of parallelism + <LI> + throughput in terms of sub problems solved, iteration count, + transactions, data sets inspected, etc. + <LI> + service time by operation type +</UL> +<P> +The <I>libpcp_trace</I> library approach offers a number of attractive +features:</P> +<UL> + <LI> + a simple API for inserting instrumentation calls into an application, + eg. + <PRE> + pmtracebegin("pass 1"); + ... + pmtraceend("pass 1"); + ... + pmtraceobs("threads", N); +</PRE> + <LI> trace routines may be called from C, C++, Fortran and Java, and are + well suited to macro encapsulation for compile-time inclusion/exclusion + <LI>the PCP version of the library allows numerical observations, measures + time between matching begin-end calls, etc. to be shipped to a PCP + agent and then exported into the PCP infrastructure ... exporting is + controlled by environment variables, so the overhead is very low if the + metrics are not being exported +</UL> +<P> +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:</P> +<UL> + <LI> + 2-D and 3-D visualization of resource demands and performance, showing + concurrent system activity and application activity + <LI> + transport of performance data over the network for distributed + performance management + <LI> + archive logging for historical records of performance, most useful for + problem diagnosis, post mortem analysis, performance regression + testing, capacity planning, benchmarking + <LI> + automated alarms when "bad" performance is observed (either + in real-time or when scanning archives) +</UL> +<P> +The relationship between the application, the <I>libpcp_trace</I> + library, the <B>trace</B> agent and the rest of the PCP infrastructure +is shown below:</P> +<CENTER><P ALIGN="CENTER"> +<IMG SRC="images/trace_libpcp.png" WIDTH="288" HEIGHT="183"></P> +</CENTER> + +<P><BR></P> +<HR> +<CENTER> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0> + <TR> <TD WIDTH=50%><P>Copyright © 2007-2010 <A HREF="http://www.aconex.com/"><FONT COLOR="#000060">Aconex</FONT></A><BR>Copyright © 2000-2004 <A HREF="http://www.sgi.com/"><FONT COLOR="#000060">Silicon Graphics Inc</FONT></P></TD> + <TD WIDTH=50%><P ALIGN=RIGHT><A HREF="http://pcp.io/"><FONT COLOR="#000060">PCP Site</FONT></A><BR>Copyright © 2012-2014 <A HREF="http://www.redhat.com/"><FONT COLOR="#000060">Red Hat</FONT></P></TD> </TR> +</TABLE> +</CENTER> +</BODY> +</HTML> diff --git a/man/html/overview.html b/man/html/overview.html new file mode 100644 index 0000000..241f97d --- /dev/null +++ b/man/html/overview.html @@ -0,0 +1,31 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> +<HTML> +<HEAD> + <meta http-equiv="content-type" content="text/html; charset=utf-8"> + <meta http-equiv="content-style-type" content="text/css"> + <link href="pcpdoc.css" rel="stylesheet" type="text/css"> + <link href="images/pcp.ico" rel="icon" type="image/ico"> + <TITLE>PCP Manual</TITLE> +</HEAD> +<BODY LANG="en-AU" TEXT="#000060" DIR="LTR"> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 STYLE="page-break-before: always"> + <TR> <TD WIDTH=64 HEIGHT=64><A HREF="http://pcp.io/"><IMG SRC="images/pmcharticon.png" NAME="pmcharticon" ALIGN=TOP WIDTH=64 HEIGHT=64 BORDER=0></A></TD> + <TD WIDTH=1><P> </P></TD> + <TD WIDTH=500><P VALIGN=MIDDLE ALIGN=LEFT><A HREF="index.html"><FONT COLOR="#cc0000">Home</FONT></A> · <A HREF="lab.pmchart.html"><FONT COLOR="#cc0000">Charts</FONT></A> · <A HREF="timecontrol.html"><FONT COLOR="#cc0000">Time Control</FONT></A></P></TD> + </TR> +</TABLE> +<H1 ALIGN=CENTER STYLE="margin-top: 0.48cm; margin-bottom: 0.32cm"><FONT SIZE=7>Overview</FONT></H1> +<P>The PCP Charts tool, pmchart, is a stripchart tool for graphically displaying changes in the values of performance metric values available through the facilities of the Performance Co-Pilot (PCP). Metric values can be sourced from one or more live hosts (simultaneously). Alternatively, one or more PCP archives can be used as a source of historical data. See the <A HREF="pcpintro.html">PCP Introduction</A> for an in-depth discussion of the capabilities of the PCP framework, many of which are used by pmchart. +<P>Many aspects of the behaviour of pmchart can be customised through the interface. The use of <A HREF="views.html">Views</A> allows predefined sets of metrics and charting parameters like colors, scaling, titles, legends, and so on to be stored for later use, or use with different hosts and archives. +<P>In addition, the Preferences dialog allows customisations to the rest of the pmchart user interface to be saved and restored between different invocations of the tool. This allows the default background color, highlight color, contents and location of the toolbar, and many other aspects to be configured. +<P>pmchart makes extensive use of the pmtime utility for <A HREF="timecontrol.html">time control</A>, refer to the pmtime manual pages for further details of its operation. +<P><BR></P> +<HR> +<CENTER> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0> + <TR> <TD WIDTH=50%><P>Copyright © 2007-2010 <A HREF="http://www.aconex.com/"><FONT COLOR="#000060">Aconex</FONT></A><BR>Copyright © 2000-2004 <A HREF="http://www.sgi.com/"><FONT COLOR="#000060">Silicon Graphics Inc</FONT></P></TD> + <TD WIDTH=50%><P ALIGN=RIGHT><A HREF="http://pcp.io/"><FONT COLOR="#000060">PCP Site</FONT></A><BR>Copyright © 2012-2014 <A HREF="http://www.redhat.com/"><FONT COLOR="#000060">Red Hat</FONT></P></TD> </TR> +</TABLE> +</CENTER> +</BODY> +</HTML> diff --git a/man/html/pcpdoc.css b/man/html/pcpdoc.css new file mode 100644 index 0000000..80201cc --- /dev/null +++ b/man/html/pcpdoc.css @@ -0,0 +1,45 @@ +h1 { + color: #000060; + font-family: Verdana,Arial,sans-serif; + font-size: 28pt; + font-style: bold; + font-weight: medium; + text-align: center; + margin-top: 0.48cm; + margin-bottom: 0.32cm; +} + +h2 { + color: #ffffff; + background-color: #081c59; + font-family: Verdana,Arial,sans-serif; + font-size: 16pt; + font-style: bold; + font-weight: medium; +} + +p, td { + color: #000060; + font-family: Verdana,Arial,sans-serif; + font-size: 11pt; +} + +li { + color: #000060; + font-family: Verdana,Arial,sans-serif; + font-size: 11pt; + padding-bottom: 5px; +} + +pre { + color: #000060; + font-size: 10pt; +} + +th { + color: #000060; + font-family: Verdana,Arial,sans-serif; + font-size: 11pt; + font-style: bold; + font-weight: medium; +} diff --git a/man/html/pcpintro.html b/man/html/pcpintro.html new file mode 100644 index 0000000..8ab3ea1 --- /dev/null +++ b/man/html/pcpintro.html @@ -0,0 +1,251 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> +<HTML> +<HEAD> + <meta http-equiv="content-type" content="text/html; charset=utf-8"> + <meta http-equiv="content-style-type" content="text/css"> + <link href="pcpdoc.css" rel="stylesheet" type="text/css"> + <link href="images/pcp.ico" rel="icon" type="image/ico"> + <TITLE>PCP Manual</TITLE> +</HEAD> +<BODY LANG="en-AU" TEXT="#000060" DIR="LTR"> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 STYLE="page-break-before: always"> + <TR> <TD WIDTH=64 HEIGHT=64><A HREF="http://pcp.io/"><IMG SRC="images/pcpicon.png" NAME="pcpicon" ALIGN=TOP WIDTH=64 HEIGHT=64 BORDER=0></A></TD> + <TD WIDTH=1><P> </P></TD> + <TD WIDTH=500><P VALIGN=MIDDLE ALIGN=LEFT><A HREF="index.html"><FONT COLOR="#cc0000">Home</FONT></A> · <A HREF="lab.pmchart.html"><FONT COLOR="#cc0000">Charts</FONT></A> · <A HREF="timecontrol.html"><FONT COLOR="#cc0000">Time Control</FONT></A></P></TD> + </TR> +</TABLE> +<H1 ALIGN=CENTER STYLE="margin-top: 0.48cm; margin-bottom: 0.32cm"><FONT SIZE=7>PCP Introduction</FONT></H1> +<P>The Performance Co-Pilot (PCP) is an open source toolkit designed for monitoring and managing system-level performance. These services are distributed and scalable to accommodate the most complex system configurations and performance problems. +<P>PCP supports many different platforms, including (but not limited to) Linux, MacOSX, FreeBSD, IRIX, Solaris and Windows (Win32). From a high-level PCP can be considered to contain two classes of software utility: +<UL> <LI><I>PCP Collectors</I>. These are the parts of PCP that collect and extract performance data from various sources, e.g. the kernel or a database. These are available from <A HREF="http://pcp.io/">http://pcp.io/</A>. +<P> <LI><I>PCP Monitors</I>. These are the parts of PCP that display data collected from hosts (or archives) that have the PCP Collector installed. Many monitor tools are available as part of PCP. Other monitoring tools are available separately, such as pmchart, in layered packages that build on the core PCP functionality. +</UL> +<P>This document describes the high-level features and options common to most PCP utilities available on all platforms. +<P> </P> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 BGCOLOR="#e2e2e2"> + <TR><TD WIDTH=100% BGCOLOR="#081c59"><P ALIGN=LEFT><FONT SIZE=5 COLOR="#ffffff"><B>Overview</B></FONT></P></TD></TR> +</TABLE> +<P>The PCP architecture is distributed in the sense that any PCP tool may be executing remotely. On the host (or hosts) being monitored, each domain of performance metrics, whether the kernel, a service layer, a database, a web server, an application, etc. requires a Performance Metrics Domain Agent (PMDA) which is responsible for collecting performance measurements from that domain. All PMDAs are controlled by the Performance Metrics Collector Daemon (<B>pmcd</B>(1)) on the same host. +<P>Client applications (the monitoring tools) connect to <B>pmcd</B>(1), which acts as a router for requests, by forwarding requests to the appropriate PMDA and returning the responses to the clients. Clients may also access performance data from a PCP archive (created using <B>pmlogger</B>(1)) for retrospective analysis. +<P>Each tool or command is documented completely in its own reference page. +<P>The following performance monitoring applications are primarily console based, are typically run directly from the command line, and are all part of the base PCP package. +<UL><LI><I>pmstat</I> - Outputs an ASCII high-level summary of system performance. + <LI><I>pmie</I> - An inference engine that can evaluate predicate-action rules to perform alarms and automate system management tasks. + <LI><I>pminfo</I> - Interrogate specific performance metrics and the meta data that describes them. + <LI><I>pmlogger</I> - Generates PCP archives of performance metrics suitable for replay by most PCP tools. + <LI><I>pmval</I> - Simple periodic reporting for some or all instances of a performance metric, with optional VCR time control. +</UL> +<P>Additional tools can be found in the layered PCP GUI package. +<UL><LI><I>pmchart</I> - Strip charts for arbitrary combinations of performance metrics. + <LI><I>pmdumptext</I> - Produce ASCII reports for arbitrary combinations of performance metrics. +</UL> +<P> </P> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 BGCOLOR="#e2e2e2"> + <TR><TD WIDTH=100% BGCOLOR="#081c59"><P ALIGN=LEFT><FONT SIZE=5 COLOR="#ffffff"><B>Common Command Line Arguments</B></FONT></P></TD></TR> +</TABLE> +<P>There is a set of common command line arguments that are used consistently by most PCP tools. +<P> </P> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 BGCOLOR="#e2e2e2"> + <TR><TD WIDTH=25%><P><B>-a archive</B></P></TD> + <TD><P>Performance metric information is retrospectively retrieved from the Performance Co-Pilot (PCP) archive, previously generated by <B>pmlogger</B>(1). The <B>-a</B> and <B>-h</B> options are mutually exclusive.</P></TD> + </TR> + <TR><TD WIDTH=25%><P><B>-a archive[,archive,..]</B></P></TD> + <TD><P>An alternate form of <B>-a</B> for applications that are able to handle multiple archives.</P></TD> + </TR> + <TR><TD WIDTH=25%><P><B>-h hostname</B></P></TD> + <TD><P>Unless directed to another host by the <B>-h</B> option, or to an archive by the <B>-a</B> option, the source of performance metrics will be the Performance Metrics Collector Daemon (PMCD) on the local host. The <B>-a</B> and <B>-h</B> options are mutually exclusive.</P></TD> + </TR> + <TR><TD WIDTH=25%><P><B>-s samples</B></P></TD> + <TD><P>The argument <B>samples</B> defines the number of samples to be retrieved and reported. If <B>samples</B> is 0 or <B>-s</B> is not specified, the application will sample and report continuously (in real time mode) or until the end of the PCP archive (in archive mode).</P></TD> + </TR> + <TR><TD WIDTH=25%><P><B>-z</B></P></TD> + <TD><P>Change the reporting timezone to the local timezone at the host that is the source of the performance metrics, as identified via either the <B>-h</B> or <B>-a</B> options.</P></TD> + </TR> + <TR><TD WIDTH=25%><P><B>-Z timezone</B></P></TD> + <TD><P>By default, applications report the time of day according to the local timezone on the system where the application is executed. The <B>-Z</B> option changes the timezone to <B>timezone</B> in the format of the environment variable TZ as described in <B>environ</B>(5).</P></TD> + </TR> +</TABLE> +<P> </P> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 BGCOLOR="#e2e2e2"> + <TR><TD WIDTH=100% BGCOLOR="#081c59"><P ALIGN=LEFT><FONT SIZE=5 COLOR="#ffffff"><B>Interval Specification and Alignment</B></FONT></P></TD></TR> +</TABLE> +<P>Most PCP tools operate with periodic sampling or reporting, and the <B>-t</B> and <B>-A</B> options may be used to control the duration of the sample interval and the alignment of the sample times. +<P> </P> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 BGCOLOR="#e2e2e2"> + <TR><TD WIDTH=25%><P><B>-t interval</B></P></TD> + <TD><P>Set the update or reporting interval.</P> +<P>The interval argument is specified as a sequence of one or more elements of the form + <I>number[units]</I> +where <I>number</I> is an integer or floating point constant (parsed using <B>strtod</B>(3)) and the optional <I>units</I> is one of: seconds, second, secs, sec, s, minutes, minute, mins, min, m, hours, hour, h, days, day and d. If the <I>unit</I> is empty, second is assumed.</P> +<P>In addition, the upper case (or mixed case) version of any of the above is also acceptable. +<P>Spaces anywhere in the <B>interval</B> are ignored, so 4 days 6 hours 30 minutes, 4day6hour30min, 4d6h30m and 4d6.5h are all equivalent. +<P>Multiple specifications are additive, e.g. ‘‘1hour 15mins 30secs’’ is interpreted as 3600+900+30 seconds. </TR> + <TR><TD WIDTH=25%><P><B>-A align</B></P></TD> + <TD><P>By default samples are not necessarily aligned on any natural unit of time. The <B>-A</B> option may be used to force the initial sample to be aligned on the boundary of a natural time unit. For example <B>-A 1sec</B>, <B>-A 30min</B> and <B>-A 1hour</B> specify alignment on whole seconds, half and whole hours respectively. +<P>The align argument follows the syntax for an interval argument described above for the <B>-t</B> option. +<P>Note that alignment occurs by advancing the time as required, and that <B>-A</B> acts as a modifier to advance both the start of the time window (see the next section) and the origin time (if the <B>-O</B> option is specified). +<P> </P></TR> +</TABLE> +<P> </P> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 BGCOLOR="#e2e2e2"> + <TR><TD WIDTH=100% BGCOLOR="#081c59"><P ALIGN=LEFT><FONT SIZE=5 COLOR="#ffffff"><B>Time Window Specification</B></FONT></P></TD></TR> +</TABLE> +<P>Many PCP tools are designed to operate in some time window of interest, e.g. to define a termination time for real time monitoring or to define a start and end time within a PCP archive log. +<P>In the absence of the <B>-O</B> and <B>-A</B> options to specify an initial sample time origin and time alignment (see above), the PCP application will retrieve the first sample at the start of the time window. +<P>The following options may be used to specify a time window of interest. +<P> </P> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 BGCOLOR="#e2e2e2"> + <TR><TD WIDTH=25%><P><B>-S starttime</B></P></TD> + <TD><P>By default the time window commences immediately in real time mode, or coincides with time at the start of the PCP archive log in archive mode. The <B>-S</B> option may be used to specify a later time for the start of the time window. +<P>The <B>starttime</B> parameter may be given in one of three forms (<B>interval</B> is the same as for the <B>-t</B> option as described above, <B>ctime</B> is described below): +<P><B>interval</B> To specify an offset from the current time (in real time mode) or the beginning of a PCP archive (in archive mode) simply specify the interval of time as the argument. For example <I>-S 30min</I> will set the start of the time window to be exactly 30 minutes from now in real time mode, or exactly 30 minutes from the start of a PCP archive. +<P><B>-interval</B> To specify an offset from the end of a PCP archive log, prefix the interval argument with a minus sign. In this case, the start of the time window precedes the time at the end of archive by the given interval. For example <I>-S -1hour</I> will set the start of the time window to be exactly one hour before the time of the last sample in a PCP archive log. +<P><B>@ctime</B> To specify the calendar date and time (local time in the reporting timezone) for the start of the time window, use the <B>ctime</B>(3) syntax preceded by an at sign. For example <I>-S ’@ Mon Mar 4 13:07:47 1996’</I>. </P></TD></TR> + <TR><TD WIDTH=25%><P><B>-T endtime</B></P></TD> + <TD><P>By default the end of the time window is unbounded (in real time mode) or aligned with the time at the end of a PCP archive log (in archive mode). The <B>-T</B> option may be used to specify an earlier time for the end of the time window. +<P>The <B>endtime</B> parameter may be given in one of three forms (interval is the same as for the <B>-t</B> option as described above, <B>ctime</B> is described below): +<P><B>interval</B> To specify an offset from the start of the time window simply use the interval of time as the argument. For example <I>-T 2h30m</I> will set the end of the time window to be 2 hours and 30 minutes after the start of the time window. +<P><B>-interval</B> To specify an offset back from the time at the end of a PCP archive log, prefix the interval argument with a minus sign. For example <I>-T -90m</I> will set the end of the time window to be 90 minutes before the time of the last sample in a PCP archive log. +<P><B>@ctime</B> To specify the calendar date and time (local time in the reporting timezone) for the end of the time window, use the <B>ctime</B>(3C) syntax preceded by an at sign. For example <I>-T ’@ Mon Mar 4 13:07:47 1996’</I>. </P></TD></TR> + <TR><TD WIDTH=25%><P><B>-O origin</B></P></TD> + <TD><P>By default samples are fetched from the start of the time window (see description of <B>-S</B> option) to the end of the time window (see description of <B>-T</B> option). The <B>-O</B> option allows the specification of an origin within the time window to be used as the initial sample time. This is useful for interactive use of a PCP tool with the <B>pmtime</B>(1) VCR replay facility. +<P>The <B>origin</B> argument accepted by <B>-O</B> conforms to the same syntax and semantics as the <B>starttime</B> argument for the <B>-T</B> option. +<P>For example <I>-O -0</I> specifies that the initial position should be at the end of the time window; this is most useful when wishing to replay "backwards" within the time window. </P></TD></TR> +</TABLE> +<P>The <B>ctime</B> argument for the <B>-O</B>, <B>-S</B> and <B>-T</B> options is based upon the calendar date and time format of <B>ctime</B>(3C), but may be a fully specified time string like <I>Mon Mar 4 13:07:47 1996</I> or a partially specified time like <I>Mar 4 1996</I>, <I>Mar 4</I>, <I>Mar</I>, <I>13:07:50</I> or <I>13:08</I>. +<P>For any missing low order fields, the default value of 0 is assumed for hours, minutes and seconds, 1 for day of the month and Jan for months. Hence, the following are equivalent: <I>-S ’@ Mar 1996’</I> and <I>-S ’@ Mar 1 00:00:00 1996’.</I> +<P>If any high order fields are missing, they are filled in by starting with the year, month and day from the current time (real time mode) or the time at the beginning of the PCP archive log (archive mode) and advancing the time until it matches the fields that are specified. So, for example if the time window starts by default at "Mon Mar 4 13:07:47 1996", then <I>-S @13:10</I> corresponds to 13:10:00 on Mon Mar 4, 1996, while <I>-S @10:00</I> corresponds to 10:00:00 on Tue Mar 5, 1996 (note this is the following day). +<P>For greater precision than afforded by <B>ctime</B>(3C), the seconds component may be a floating point number. +<P>Also the 12 hour clock (am/pm notation) is supported, so for example <I>13:07</I> and <I>1:07 pm</I> are equivalent. +<P> </P> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 BGCOLOR="#e2e2e2"> + <TR><TD WIDTH=100% BGCOLOR="#081c59"><P ALIGN=LEFT><FONT SIZE=5 COLOR="#ffffff"><B>Performance Metrics - Names and Identifiers</B></FONT></P></TD></TR> +</TABLE> +<P>The number of performance metric names supported by PCP in IRIX is of the order of a few thousand. There are fewer metrics on Linux, but still a considerable number. The PCP libraries and applications use an internal identification scheme that unambiguously associates a single integer with each known performance metric. This integer is known as the Performance Metric Identifier, or PMID. Although not a requirement, PMIDs tend to have global consistency across all systems, so a particular performance metric usually has the same PMID. +<P>For all users and most applications, direct use of the PMIDs would be inappropriate (e.g. this would limit the range of accessible metrics, make the code hard to maintain, force the user interface to be particularly baroque, etc.). Hence a Performance Metrics Name Space (PMNS) is used to provide external names and a hierarchic classification for performance metrics. A PMNS is represented as a tree, with each node having a label, a pointer to either a PMID (for leaf nodes) or a set of descendent nodes in the PMNS (for non-leaf nodes). +<P>A node label must begin with an alphabetic character, followed by zero or more characters drawn from the alphabetics, the digits and character `_´ (underscore). For alphabetic characters in a node label, upper and lower case are distinguished. +<P>By convention, the name of a performance metric is constructed by concatenation of the node labels on a path through the PMNS from the root node to a leaf node, with a ‘‘.’’ as a separator. The root node in the PMNS is unlabeled, so all names begin with the label associated with one of the descendent nodes below the root node of the PMNS, e.g. <I>kernel.percpu.syscall</I>. Typically (although this is not a requirement) there would be at most one name for each PMID in a PMNS. For example <I>kernel.all.cpu.idle</I> and <I>disk.dev.read</I> are the unique names for two distinct performance metrics, each with a unique PMID. +<P>Groups of related PMIDs may be named by naming a non-leaf node in the PMNS tree, e.g. <I>disk</I>. +<P>There may be PMIDs with no associated name in a PMNS; this is most likely to occur when specific PMIDs are not available in all systems, e.g. if ORACLE is not installed on a system, there is no good reason to pollute the PMNS with names for all of the ORACLE performance metrics. +<P>Note also that there is no requirement for the PMNS to be the same on all systems, however in practice most applications would be developed against a stable PMNS that was assumed to be a subset of the PMNS on all systems. Indeed the PCP distribution includes a default local PMNS for just this purpose. +<P>The default local PMNS is located at $PCP_VAR_DIR/pmns/root however the environment variable PMNS_DEFAULT may be set to the full pathname of a different PMNS which will then be used as the default local PMNS. +<P>Most applications do not use the local PMNS, but rather import parts of the PMNS as required from the same place that performance metrics are fetched, i.e. from <B>pmcd</B>(1) for live monitoring or from a PCP archive for retrospective monitoring. +<P>To explore the PMNS use <B>pminfo</B>(1), or if the PCP GUI package is installed the New Chart and Metric Search windows within <B>pmchart</B>(1). +<P> </P> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 BGCOLOR="#e2e2e2"> + <TR><TD WIDTH=100% BGCOLOR="#081c59"><P ALIGN=LEFT><FONT SIZE=5 COLOR="#ffffff"><B>Performance Metric Specifications</B></FONT></P></TD></TR> +</TABLE> +<P>In configuration files and (to a lesser extent) command line options, metric specifications adhere to the following syntax rules. +<P>If the source of performance metrics is real time from <B>pmcd</B>(1) then the accepted syntax is +<P><I> host:metric[instance1,instance2,...]</I> +<P>If the source of performance metrics is a PCP archive log then the accepted syntax is +<P><I> archive/metric[instance1,instance2,...]</I> +<P>The host:, archive/ and [instance1,instance2,...] components are all optional. +<P>The <B>,</B> delimiter in the list of instance names may be replaced by whitespace. +<P>Special characters in instance names may be escaped by surrounding the name in double quotes or preceding the character with a backslash. +<P>White space is ignored everywhere except within a quoted instance name. +<P>An empty instance is silently ignored, and in particular ‘‘[]’’ is the same as no instance, while ‘‘[one,,,two]’’ is parsed as specifying just the two instances ‘‘one’’ and ‘‘two’’. +<P> </P> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 BGCOLOR="#e2e2e2"> + <TR><TD WIDTH=100% BGCOLOR="#081c59"><P ALIGN=LEFT><FONT SIZE=5 COLOR="#ffffff"><B>PMCD and Archive Versions</B></FONT></P></TD></TR> +</TABLE> +<P>Since PCP version 2, version information has been associated with <B>pmcd</B>(1) and PCP archives. The version number is used in a number of ways, but most noticeably for the distributed pmns(4). In PCP version 1, the client applications would load the PMNS from the default PMNS file but in PCP version 2, the client applications extract the PMNS information from <B>pmcd</B> or a PCP archive. Thus in PCP version 2, the version number is used to determine if the PMNS to use is from the default local file or from the actual current source of the metrics. +<P> </P> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 BGCOLOR="#e2e2e2"> + <TR><TD WIDTH=100% BGCOLOR="#081c59"><P ALIGN=LEFT><FONT SIZE=5 COLOR="#ffffff"><B>Environment</B></FONT></P></TD></TR> +</TABLE> +<P>In addition to the PCP run time environment and configuration variables described in the PCP Environment section below, the following environment variables apply to all installations. +<P> </P> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 BGCOLOR="#e2e2e2"> + <TR><TD WIDTH=25%><P><B>PCP_STDERR</B></P></TD> + <TD><P>Many PCP tools support the environment variable <B>PCP_STDERR</B>, which can be used to control where error messages are sent. When unset, the default behavior is that ‘‘usage’’ messages and option parsing errors are reported on standard error, other messages after initial startup are sent to the default destination for the tool, i.e. standard error for ASCII tools, or a dialog for GUI tools. +<P>If <B>PCP_STDERR</B> is set to the literal value <B>DISPLAY</B> then all messages will be displayed in a dialog. This is used for any tools launched from a Desktop environment. +<P>If <B>PCP_STDERR</B> is set to any other value, the value is assumed to be a filename, and all messages will be written there.</P></TD></TR> + <TR><TD WIDTH=25%><P><B>PMCD_CONNECT_TIMEOUT</B></P></TD> + <TD><P>When attempting to connect to a remote <B>pmcd</B>(1) on a machine that is booting, the connection attempt could potentially block for a long time until the remote machine finishes its initialization. +<P>Most PCP applications and some of the PCP library routines will 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 <B>PMCD_CONNECT_TIMEOUT</B> in the environment to a real number of seconds for the desired timeout. 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.</P></TD></TR> + <TR><TD WIDTH=25%><P><B>PMCD_RECONNECT_TIMEOUT</B></P></TD> + <TD><P>When a monitor or client application loses a connection to a <B>pmcd</B>(1), the connection may be re-established by calling a service routine in the PCP library. 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 will be repeated for any further attempts after the fifth). Setting the environment variable <B>PMCD_RECONNECT_TIMEOUT</B> to a comma separated list of positive integers will re-define the back-off delays, e.g. setting <B>PMCD_RECONNECT_TIMEOUT</B> to ‘‘1,2’’ will back-off for 1 second, then attempt another connection request every 2 seconds thereafter. <P></TD></TR> + <TR><TD WIDTH=25%><P><B>PMCD_WAIT_TIMEOUT</B></P></TD> + <TD><P>When <B>pmcd</B>(1) is started from <I>$PCP_RC_DIR/pcp</I> then the primary instance of <B>pmlogger</B>(1) will be started if the configuration flag pmlogger is <B>chkconfig</B>’ed on and <B>pmcd</B> is running and accepting connections. +<P>The check on <B>pmcd</B>’s readiness will wait up to <B>PMCD_WAIT_TIMEOUT</B> seconds. If pmcd has a long startup time (such as on a very large system), then PMCD_WAIT_TIMEOUT can be set to provide a maximum wait longer than the default 60 seconds.</P></TD></TR> + <TR><TD WIDTH=25%><P><B>PMNS_DEFAULT</B></P></TD> + <TD><P>If set, then this is interpreted as the the full pathname to be used as the default local PMNS for <B>pmLoadNameSpace</B>(3). Otherwise, the default local PMNS is located at <I>$PCP_VAR_DIR/pcp/pmns/root</I> for base PCP installations.</P></TD></TR> + <TR><TD WIDTH=25%><P><B>PCP_COUNTER_WRAP</B></P></TD> + <TD><P>Many of the performance metrics exported from PCP agents have the semantics of <I>counter</I> meaning they are expected to be monotonically increasing. Under some circumstances, one value of these metrics may be less than the previously fetched value. This can happen when a counter of finite precision overflows, or when the PCP agent has been reset or restarted, or when the PCP agent is exporting values from some underlying instrumentation that is subject to some asynchronous discontinuity. +<P>The environment variable <B>PCP_COUNTER_WRAP</B> may be set to indicate that all such cases of a decreasing <I>counter</I> should be treated as a counter overflow, and hence the values are assumed to have wrapped once in the interval between consecutive samples. This ‘‘wrapping’’ behavior was the default in earlier PCP versions, but by default has been disabled in PCP release from version 1.3 on.</P></TD></TR> + <TR><TD WIDTH=25%><P><B>PMDA_PATH</B></P></TD> + <TD><P>The <B>PMDA_PATH</B> environment variable may be used to modify the search path used by <B>pmcd</B>(1) and <B>pmNewContext</B>(3) (for PM_CONTEXT_LOCAL contexts) when searching for a daemon or DSO PMDA. The syntax follows that for <B>PATH</B> in <B>sh</B>(1), i.e. a colon separated list of directories, and the default search path is ‘‘/var/pcp/lib:/usr/pcp/lib’’, (or ‘‘/var/lib/pcp/lib’’ on Linux, depending on the value of the $PCP_VAR_DIR environment variable).</P></TD></TR> + <TR><TD WIDTH=25%><P><B>PMCD_PORT</B></P></TD> + <TD><P>The TPC/IP port(s) used by <B>pmcd</B>(1) to create the socket for incoming connections and requests, was historically 4321 and more recently the officially registered port 44321; in the current release, both port numbers are used by default as a transitional arrangement. This may be over-ridden by setting PMCD_PORT to a different port number, or a comma-separated list of port numbers. If a non-default port is used when <B>pmcd</B>(1) is started, then every monitoring application connecting to that <B>pmcd</B>(1) must also have <B>PMCD_PORT</B> set in their environment before attempting a connection.</P></TD></TR> +</TABLE> +<P>The following environment variables are relevant to installations in which <B>pmlogger</B>(1), the PCP archive logger, is used. +<P> </P> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 BGCOLOR="#e2e2e2"> + <TR><TD WIDTH=25%><P><B>PMLOGGER_PORT</B></P></TD> + <TD><P>The environment variable <B>PMLOGGER_PORT</B> may be used to change the base TCP/IP port number used by <B>pmlogger</B>(1) to create the socket to which <B>pmlc</B>(1) instances will try and connect. The default base port number is 4330. When used, <B>PMLOGGER_PORT</B> should be set in the environment before <B>pmlogger</B>(1) is executed.</P></TD></TR> +</TABLE> +<P>If you have the PCP package installed, then the following environment variables are relevant to the Performance Metrics Domain Agents (PMDAs). +<P> </P> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 BGCOLOR="#e2e2e2"> + <TR><TD WIDTH=25%><P><B>PMDA_LOCAL_PROC</B></P></TD> + <TD><P>If set, then a context established with the type of <B>PM_CONTEXT_LOCAL</B> will have access to the ‘‘proc’’ PMDA to retrieve performance metrics about individual processes.</P></TD></TR> + <TR><TD WIDTH=25%><P><B>PMDA_LOCAL_SAMPLE</B></P></TD> + <TD><P>If set, then a context established with the type of PM_CONTEXT_LOCAL will have access to the ‘‘sample’’ PMDA if this optional PMDA has been installed locally.</P></TD></TR> + <TR><TD WIDTH=25%><P><B>PMIECONF_PATH</B></P></TD> + <TD><P>If set, <B>pmieconf</B>(1) will form its <B>pmieconf</B>(4) specification (set of parameterized <B>pmie</B>(1) rules) using all valid <B>pmieconf</B> files found below each subdirectory in this colon-separated list of subdirectories. If not set, the default is $PCP_VAR_DIR/config/pmieconf.</P></TD></TR> +</TABLE> +<P> </P> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 BGCOLOR="#e2e2e2"> + <TR><TD WIDTH=100% BGCOLOR="#081c59"><P ALIGN=LEFT><FONT SIZE=5 COLOR="#ffffff"><B>Files</B></FONT></P></TD></TR> +</TABLE> +<P> </P> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 BGCOLOR="#e2e2e2"> + <TR><TD WIDTH=25%><P><B>/etc/pcp.conf</B></P></TD> + <TD><P>Configuration file for the PCP runtime environment, see <B>pcp.conf</B>(4).</P></TD></TR> + <TR><TD WIDTH=25%><P><B>$PCP_RC_DIR/pcp</B></P></TD> + <TD><P>Script for starting and stopping <B>pmcd</B>(1).</P></TD></TR> + <TR><TD WIDTH=25%><P><B>$PCP_PMCDCONF_PATH</B></P></TD> + <TD><P>Control file for <B>pmcd</B>(1).</P></TD></TR> + <TR><TD WIDTH=25%><P><B>$PCP_PMCDOPTIONS_PATH</B></P></TD> + <TD><P>Command line options passed to <B>pmcd</B>(1) when it is started from <B>$PCP_RC_DIR/pcp</B>. All the command line option lines should start with a hyphen as the first character. This file can also contain environment variable settings of the form "VARIABLE=value". +</P></TD></TR> + <TR><TD WIDTH=25%><P><B>$PCP_BINADM_DIR</B></P></TD> + <TD><P>Location of PCP utilities for collecting and maintaining PCP archives, PMDA help text, PMNS files etc.</P></TD></TR> + <TR><TD WIDTH=25%><P><B>$PCP_PMDAS_DIR</B></P></TD> + <TD><P>Parent directory of the installation directory for Dynamic Shared Object (DSO) PMDAs.</P></TD></TR> + <TR><TD WIDTH=25%><P><B>$PCP_RUN_DIR/pmcd.pid</B></P></TD> + <TD><P>If pmcd is running, this file contains an ascii decimal representation of its process ID.</P></TD></TR> + <TR><TD WIDTH=25%><P><B>$PCP_LOG_DIR/pmcd</B></P></TD> + <TD><P>Default location of log files for <B>pmcd</B>(1), current directory for running PMDAs. Archives generated by <B>pmlogger</B>(1) are generally below <B>$PCP_LOG_DIR/pmlogger</B>.</P></TD></TR> + <TR><TD WIDTH=25%><P><B>$PCP_LOG_DIR/pmcd/pmcd.log</B></P></TD> + <TD><P>Diagnostic and status log for the current running <B>pmcd</B>(1) process. The first place to look when there are problems associated with <B>pmcd</B>.</P></TD></TR> + <TR><TD WIDTH=25%><P><B>$PCP_LOG_DIR/pmcd/pmcd.log.prev</B></P></TD> + <TD><P>Diagnostic and status log for the previous <B>pmcd</B>(1) instance.</P></TD></TR> + <TR><TD WIDTH=25%><P><B>$PCP_LOG_DIR/NOTICES</B></P></TD> + <TD><P>Log of <B>pmcd</B>(1) and PMDA starts, stops, additions and removals.</P></TD></TR> + <TR><TD WIDTH=25%><P><B>$PCP_VAR_DIR/config</B></P></TD> + <TD><P>Contains directories of configuration files for several PCP tools.</P></TD></TR> + <TR><TD WIDTH=25%><P><B>$PCP_VAR_DIR/config/pmcd/rc.local</B></P></TD> + <TD><P>Local script for controlling PCP boot, shutdown and restart actions.</P></TD></TR> + <TR><TD WIDTH=25%><P><B>$PCP_VAR_DIR/pmns/root</B></P></TD> + <TD><P>The ASCII <B>$PCP_LOG_DIR/NOTICES/pmns</B>(4) exported by <B>pmcd</B>(1) by default. This PMNS is be the super set of all other PMNS files installed in <B>$PCP_VAR_DIR/pmns</B>.</P></TD></TR> + <TR><TD WIDTH=25%><P><B>$PCP_LOG_DIR/NOTICES</B></P></TD> + <TD><P>In addition to the <B>pmcd</B>(1) and PMDA activity, may be used to log alarms and notices from <B>pmie</B>(1) via <B>pmpost</B>(1). </P></TD></TR> + <TR><TD WIDTH=25%><P><B>$PCP_VAR_DIR/config/pmlogger/control</B></P></TD> + <TD><P>Control file for <B>pmlogger</B>(1) instances launched from <B>$PCP_RC_DIR/pcp</B> and/or managed by <B>pmlogger_check</B>(1) and <B>pmlogger_daily</B>(1) as part of a production PCP archive collection setup.</P></TD></TR> +</TABLE> +<P> </P> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 BGCOLOR="#e2e2e2"> + <TR><TD WIDTH=100% BGCOLOR="#081c59"><P ALIGN=LEFT><FONT SIZE=5 COLOR="#ffffff"><B>PCP Environment</B></FONT></P></TD></TR> +</TABLE> +<P>Environment variables with the prefix PCP_ are used to parameterize the file and directory names used by PCP. On each installation, the file <B>/etc/pcp.conf</B> contains the local values for these variables. The <B>$PCP_CONF</B> variable may be used to specify an alternative configuration file, as described in <B>pcp.conf</B>(4). +<HR> +<CENTER> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0> + <TR> <TD WIDTH=50%><P>Copyright © 2007-2010 <A HREF="http://www.aconex.com/"><FONT COLOR="#000060">Aconex</FONT></A><BR>Copyright © 2000-2004 <A HREF="http://www.sgi.com/"><FONT COLOR="#000060">Silicon Graphics Inc</FONT></P></TD> + <TD WIDTH=50%><P ALIGN=RIGHT><A HREF="http://pcp.io/"><FONT COLOR="#000060">PCP Site</FONT></A><BR>Copyright © 2012-2014 <A HREF="http://www.redhat.com/"><FONT COLOR="#000060">Red Hat</FONT></P></TD> </TR> +</TABLE> +</CENTER> +</BODY> +</HTML> diff --git a/man/html/pmchart.html b/man/html/pmchart.html new file mode 100644 index 0000000..76c1a07 --- /dev/null +++ b/man/html/pmchart.html @@ -0,0 +1,34 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> +<HTML> +<HEAD> + <meta http-equiv="content-type" content="text/html; charset=utf-8"> + <meta http-equiv="content-style-type" content="text/css"> + <link href="pcpdoc.css" rel="stylesheet" type="text/css"> + <link href="images/pcp.ico" rel="icon" type="image/ico"> + <TITLE>PCP Charts</TITLE> +</HEAD> +<BODY LANG="en-AU" TEXT="#000060" DIR="LTR"> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 STYLE="page-break-before: always"> + <TR> <TD WIDTH=64 HEIGHT=64><A HREF="http://pcp.io/"><IMG SRC="images/pmcharticon.png" NAME="pmcharticon" ALIGN=TOP WIDTH=64 HEIGHT=64 BORDER=0></A></TD> + <TD WIDTH=1><P> </P></TD> + <TD WIDTH=500><P VALIGN=MIDDLE ALIGN=LEFT><A HREF="index.html"><FONT COLOR="#cc0000">Home</FONT></A> · <A HREF="lab.pmchart.html"><FONT COLOR="#cc0000">Charts</FONT></A> · <A HREF="timecontrol.html"><FONT COLOR="#cc0000">Time Control</FONT></A></P></TD> + </TR> +</TABLE> +<H1 ALIGN=CENTER STYLE="margin-top: 0.48cm; margin-bottom: 0.32cm"><FONT SIZE=7>Notes for pmchart users</FONT></H1> +<P>Users of the original SGI pmchart utility will be immediately at home with the new pmchart. This page discusses two areas where differences are more likely to be noticed by people familiar with pmchart. +<h2>Configuration file syntax</h2> +<P>pmchart provides the ability to parse and interpret all versions of the original SGI pmchart configuration file language (i.e. versions 1, 1.1, 1.2 and 2.0. In addition, the new pmchart provides it's own configuration file syntax extensions, which both addresses some of the quirkier aspects of the original pmchart language and provides support for features specific to pmchart (Legend Labels and Tabs, for example). +<P>Refer to the discussion of pmchart <A HREF="views.html">Views</A> for a detailed description of the configuration language. +<P>Finally, while pmchart will read all versions of configuration files, it does not implement support for writing the older formats - only the latest format is written during a View save operation. +<H2>User interface changes</H2> +<P>While every effort has been made to keep all of the excellent features of the original user interface, pmchart now provides support for several new user interface advances above and beyond those features of the original tool. +<P><BR></P> +<HR> +<CENTER> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0> + <TR> <TD WIDTH=50%><P>Copyright © 2007-2010 <A HREF="http://www.aconex.com/"><FONT COLOR="#000060">Aconex</FONT></A><BR>Copyright © 2000-2004 <A HREF="http://www.sgi.com/"><FONT COLOR="#000060">Silicon Graphics Inc</FONT></P></TD> + <TD WIDTH=50%><P ALIGN=RIGHT><A HREF="http://pcp.io/"><FONT COLOR="#000060">PCP Site</FONT></A><BR>Copyright © 2012-2014 <A HREF="http://www.redhat.com/"><FONT COLOR="#000060">Red Hat</FONT></P></TD> </TR> +</TABLE> +</CENTER> +</BODY> +</HTML> diff --git a/man/html/pmie/GNUmakefile b/man/html/pmie/GNUmakefile new file mode 100644 index 0000000..07336fa --- /dev/null +++ b/man/html/pmie/GNUmakefile @@ -0,0 +1,31 @@ +TOPDIR = ../../.. +include $(TOPDIR)/src/include/builddefs + +BUNDLE = pmie +BINTAR = $(BUNDLE).tar.gz +PCPLOGS = $(shell echo *.0 *.meta *.index) +CONFIGS = pswitch.view pswitch.pmie disk.pmie answer.pmie +LSRCFILES = $(PCPLOGS) $(CONFIGS) +LDIRT = $(BINTAR) manifest + +default: $(BINTAR) + +$(BINTAR): $(PCPLOGS) $(CONFIGS) + @ CDIR=`pwd`; cd ..; rm -f manifest; \ + for f in `echo $^`; do \ + echo $(BUNDLE)/$$f >> $$CDIR/manifest; \ + done; \ + $(TAR) -T $$CDIR/manifest -cf - | $(ZIP) --best > $$CDIR/$(BINTAR); \ + echo "Created $(BINTAR)" + +include $(BUILDRULES) + +install install-dev: default + $(INSTALL) -m 755 -d $(PCP_DEMOS_DIR)/tutorials + $(INSTALL) -m 644 $(BINTAR) $(PCP_DEMOS_DIR)/tutorials/$(BINTAR) + $(INSTALL) -m 755 -d $(PCP_BOOKS_DIR)/html/$(BUNDLE) + $(INSTALL) -m 644 $(CONFIGS) $(PCP_BOOKS_DIR)/html/$(BUNDLE) + +default_pcp : default + +install_pcp : install diff --git a/man/html/pmie/answer.pmie b/man/html/pmie/answer.pmie new file mode 100644 index 0000000..013d25a --- /dev/null +++ b/man/html/pmie/answer.pmie @@ -0,0 +1,23 @@ +// +// solution for the pmie tutorial +// + +// show any disk doing more than 50 I/Os per second +some_inst ( disk.dev.total > 50 ) -> print "high IOPs:" " %i: %v"; + +// some disk is doing more than 30 reads per second +some_inst ( disk.dev.read > 30 ) -> print "busy reads:" " %i: %v"; + +// some disk is doing more than 30 writes per second +some_inst ( disk.dev.write > 30 ) -> print "busy writes:" " %i: %v"; + +// some disk has a high I/O rate and more than 95% reads +some_inst ( disk.dev.total > 40 && + disk.dev.read / disk.dev.total > 0.95 ) +-> print "busy disk and >95% writes"; + +// some disk has a high I/O rate and 1 minute load average is +// greater than 5 +kernel.all.load #'1 minute' > 5 && +some_inst ( disk.dev.total > 40 ) +-> print "busy disk and high load avg"; diff --git a/man/html/pmie/babylon.perdisk.0 b/man/html/pmie/babylon.perdisk.0 Binary files differnew file mode 100644 index 0000000..7a1f26f --- /dev/null +++ b/man/html/pmie/babylon.perdisk.0 diff --git a/man/html/pmie/babylon.perdisk.index b/man/html/pmie/babylon.perdisk.index Binary files differnew file mode 100644 index 0000000..72b4af9 --- /dev/null +++ b/man/html/pmie/babylon.perdisk.index diff --git a/man/html/pmie/babylon.perdisk.meta b/man/html/pmie/babylon.perdisk.meta Binary files differnew file mode 100644 index 0000000..6004327 --- /dev/null +++ b/man/html/pmie/babylon.perdisk.meta diff --git a/man/html/pmie/disk.pmie b/man/html/pmie/disk.pmie new file mode 100644 index 0000000..3a15780 --- /dev/null +++ b/man/html/pmie/disk.pmie @@ -0,0 +1,7 @@ +// +// pmie configuration file starting point for the pmie lab +// + +// show any disk doing more than 40 I/Os per second +some_inst ( disk.dev.total > 40 ) -> print "busy IOPs:" " %i: %v"; + diff --git a/man/html/pmie/pswitch.pmie b/man/html/pmie/pswitch.pmie new file mode 100644 index 0000000..34c706a --- /dev/null +++ b/man/html/pmie/pswitch.pmie @@ -0,0 +1,5 @@ +// Sample interval +delta = 5 sec; + +// If context switch rate exceeds 2000 per second, display an alarm notifier. +kernel.all.pswitch > 2000 count/sec -> alarm "high context switch rate"; diff --git a/man/html/pmie/pswitch.view b/man/html/pmie/pswitch.view new file mode 100644 index 0000000..1e6f9d5 --- /dev/null +++ b/man/html/pmie/pswitch.view @@ -0,0 +1,14 @@ +#kmchart +version 1 + +chart title "CPU Utilization" style utilization + plot legend "User" color #2d2de2 metric kernel.all.cpu.user + plot legend "Kernel" color #e71717 metric kernel.all.cpu.sys + optional-plot legend "Nice" color #c2f3c2 metric kernel.all.cpu.nice + optional-plot legend "Intr" color #cdcd00 metric kernel.all.cpu.intr + optional-plot legend "Wait" color #00cdcd metric kernel.all.cpu.wait.total + optional-plot legend "Steal" color #fba2f5 metric kernel.all.cpu.steal + plot legend "Idle" color #16d816 metric kernel.all.cpu.idle + +chart title "Context Switch Rate" style plot + plot color yellow metric kernel.all.pswitch diff --git a/man/html/pmview/GNUmakefile b/man/html/pmview/GNUmakefile new file mode 100644 index 0000000..f33a089 --- /dev/null +++ b/man/html/pmview/GNUmakefile @@ -0,0 +1,31 @@ +TOPDIR = ../../.. +include $(TOPDIR)/src/include/builddefs + +BUNDLE = pmview +BINTAR = $(BUNDLE).tar.gz +PCPLOGS = $(shell echo *.0 *.meta *.index) +CONFIGS = godzilla.web.view godzilla.web.folio example.view +LSRCFILES = $(PCPLOGS) $(CONFIGS) +LDIRT = $(BINTAR) manifest + +default: $(BINTAR) + +$(BINTAR): $(PCPLOGS) $(CONFIGS) + @ CDIR=`pwd`; cd ..; rm -f manifest; \ + for f in `echo $^`; do \ + echo $(BUNDLE)/$$f >> $$CDIR/manifest; \ + done; \ + $(TAR) -T $$CDIR/manifest -cf - | $(ZIP) --best > $$CDIR/$(BINTAR); \ + echo "Created $(BINTAR)" + +include $(BUILDRULES) + +install install-dev: default + $(INSTALL) -m 755 -d $(PCP_DEMOS_DIR)/tutorials + $(INSTALL) -m 644 $(BINTAR) $(PCP_DEMOS_DIR)/tutorials/$(BINTAR) + $(INSTALL) -m 755 -d $(PCP_BOOKS_DIR)/html/$(BUNDLE) + $(INSTALL) -m 644 $(CONFIGS) $(PCP_BOOKS_DIR)/html/$(BUNDLE) + +default_pcp : default + +install_pcp : install diff --git a/man/html/pmview/example.view b/man/html/pmview/example.view new file mode 100644 index 0000000..2f61785 --- /dev/null +++ b/man/html/pmview/example.view @@ -0,0 +1,38 @@ +pmview Version 2.1 +# +# pmview configuration used as a starting point in the pmview exercises. +# + +_colorlist ctrl_colors ( green2 ) + +_grid hide ( + _label 0 1 _down _large "Disk" + + _bar 1 1 _west ( + _metrics ( + disk.all.read 100 + ) + _colorlist ctrl_colors + _baseLabel "Disk Reads\nNormalized to 100 reads/second" + ) + + _bar 2 1 _west ( + _metrics ( + disk.all.write 100 + ) + _colorlist ctrl_colors + _baseLabel "Disk Writes\nNormalized to 100 writes/second" + ) + + _label 0 3 _west _down _large "Load" + _bar 1 3 2 1 _west ( + _metrics ( + kernel.all.load[15] 2 + kernel.all.load[5] 2 + kernel.all.load[1] 2 + ) + _metriclabels _away ( "15" "5" "1" ) + _colorlist ( blue2 blue2 blue2 ) + _baseLabel "Average System Load over the last 1, 5, and 15 minutes\nNormalized to 2" + ) +) diff --git a/man/html/pmview/godzilla.disk.0 b/man/html/pmview/godzilla.disk.0 Binary files differnew file mode 100644 index 0000000..d06d4e8 --- /dev/null +++ b/man/html/pmview/godzilla.disk.0 diff --git a/man/html/pmview/godzilla.disk.index b/man/html/pmview/godzilla.disk.index Binary files differnew file mode 100644 index 0000000..053a3ee --- /dev/null +++ b/man/html/pmview/godzilla.disk.index diff --git a/man/html/pmview/godzilla.disk.meta b/man/html/pmview/godzilla.disk.meta Binary files differnew file mode 100644 index 0000000..4f7d1da --- /dev/null +++ b/man/html/pmview/godzilla.disk.meta diff --git a/man/html/pmview/godzilla.web.0 b/man/html/pmview/godzilla.web.0 Binary files differnew file mode 100644 index 0000000..3a9467b --- /dev/null +++ b/man/html/pmview/godzilla.web.0 diff --git a/man/html/pmview/godzilla.web.folio b/man/html/pmview/godzilla.web.folio new file mode 100644 index 0000000..5d12e2a --- /dev/null +++ b/man/html/pmview/godzilla.web.folio @@ -0,0 +1,9 @@ +PCPFolio +Version: 1 +# +# use pmafm(1) to process this PCP Archive Folio +# +Created: on godzilla at Mon Mar 26 17:11:33 2001 +Creator: pmview godzilla.web.view +# Host Basename +Archive: godzilla godzilla.web diff --git a/man/html/pmview/godzilla.web.index b/man/html/pmview/godzilla.web.index Binary files differnew file mode 100644 index 0000000..178700e --- /dev/null +++ b/man/html/pmview/godzilla.web.index diff --git a/man/html/pmview/godzilla.web.meta b/man/html/pmview/godzilla.web.meta Binary files differnew file mode 100644 index 0000000..0d7dee9 --- /dev/null +++ b/man/html/pmview/godzilla.web.meta diff --git a/man/html/pmview/godzilla.web.view b/man/html/pmview/godzilla.web.view new file mode 100644 index 0000000..652e3b9 --- /dev/null +++ b/man/html/pmview/godzilla.web.view @@ -0,0 +1,240 @@ +pmview Version 2.1 "webvis" + +_stackLength 26 +_marginWidth 8 +_marginDepth 8 + +_colorList cpu_colors ( blue2 red2 yellow2 cyan2 ) +_colorList disk_colors ( violet yellow ) +_colorList memory_colors ( + rgbi:1.0/1.0/0.0 + rgbi:0.0/1.0/1.0 + rgbi:1.0/0.0/0.0 + rgbi:1.0/0.0/1.0 + rgbi:0.0/0.0/1.0 + rgbi:0.0/1.0/0.0 +) +_colorList network_colors ( + rgbi:0.8/0.0/0.0 + rgbi:1.0/0.5/0.0 + rgbi:0.0/0.8/0.0 +) +_colorList type_colors ( + rgbi:0.8/0.0/0.0 + rgbi:1.0/1.0/0.6 + rgbi:1.0/0.0/1.0 + rgbi:0.0/1.0/1.0 + rgbi:1.0/1.0/0.0 +) + +_colorList size_colors ( + rgbi:1.0/0.35/0.0 + rgbi:0.6/0.0/0.9 + rgbi:0.0/1.0/0.0 + rgbi:1.0/0.5/0.0 + rgbi:0.65/0.3/1.0 + rgbi:0.3/1.0/0.3 + rgbi:1.0/0.65/0.3 + rgbi:0.8/0.6/1.0 + rgbi:0.6/1.0/0.6 + rgbi:1.0/0.8/0.6 +) + +_grid _hide ( + _grid 1 0 6 2 south _hide ( + _bar 0 1 6 1 west _row _groupbyrow ( + _metrics ( + network.tcp.drops 7 + network.tcp.conndrops 7 + network.tcp.timeoutdrop 7 + network.tcp.rcvbadsum 7 + network.tcp.rexmttimeo 7 + network.tcp.sndrexmitpack 7 + ) + _colorList ( + red1 red1 red1 red1 red1 red1 + ) + _baseLabel "TCP metrics which may indicate a problem\nNormalized to 7 events per second" + ) + _bar 0 0 3 1 west _row _groupbyrow ( + _metrics ( + swap.pagesout 7 + network.mbuf.failed 7 + network.mbuf.waited 7 + ) + _colorList ( + yellow rgbi:1.0/0.5/0.0 rgbi:1.0/0.5/0.0 + ) + _baseLabel "Memory metrics which may indicate a problem\nNormalized to 7 events per second" + ) + _label 3 0 west _right _medium "Alarms" + ) + + _bar 0 1 1 10 south _groupbycol ( + _metrics ( + web.allservers.requests.size.unknown 37 + web.allservers.requests.size.gt3m 37 + web.allservers.requests.size.le3m 37 + web.allservers.requests.size.le1m 37 + web.allservers.requests.size.le300k 37 + web.allservers.requests.size.le100k 37 + web.allservers.requests.size.le30k 37 + web.allservers.requests.size.le10k 37 + web.allservers.requests.size.le3k 37 + web.allservers.requests.size.zero 37 + ) + _metriclabels _towards ( + "?" ">3M" "3M" "1M" "300k" + "100k" "30k" "10k" "3k" "0k" + ) + _colorList size_colors + _baseLabel "HTTP request rate by response size in bytes\nNormalized to 37 hits per second" + ) + + _label 0 11 northeast _right _medium "Size" + + _bar 1 6 1 5 south _groupbycol ( + _metrics ( + web.allservers.errors 7 + web.allservers.requests.other 37 + web.allservers.requests.post 37 + web.allservers.requests.head 37 + web.allservers.requests.get 37 + ) + _colorList type_colors + _baseLabel "HTTP request rate by HTTP method\nNormalized to 37 hits per second" + ) + + _label 1 11 north _right _medium "Type" + + _grid 1 3 5 3 southwest ( + _stack 0 0 ( + _metrics ( + kernel.all.cpu.user 1000 + kernel.all.cpu.sys 1000 + kernel.all.cpu.intr 1000 + kernel.all.cpu.wait.total 1000 + ) + _colorList cpu_colors + _baseLabel "CPU Utilization\nSummed over 1 CPU" + ) + _label 0 1 north _right _medium "CPU" + +_marginWidth 4 +_marginDepth 4 +_baseHeight 4 + + _grid 1 0 2 1 _show ( +_baseColor rgbi:0.30/0.30/0.30 + _stack 0 0 south _cylinder ( + _metrics ( + disk.all.write 100 + disk.all.read 100 + ) + _colorList disk_colors + _baseLabel "Read and Write activity for all Disks\nNormalized to 100 I/Os per second" + ) + _bar 1 0 _cylinder ( + _metrics ( + disk.all.avg_disk.active 300 + ) + _colorList ( green2 ) + _baseLabel "Average Disk Utilization\nNormalized to 30% across 2 disks" + ) +_baseColor rgbi:0.15/0.15/0.15 + ) + _label 1 1 2 1 north _medium "Disk" + + _grid 3 0 2 1 _show ( +_baseColor rgbi:0.30/0.30/0.30 + _stack 0 0 ( + _metrics ( + mem.freemem 98304 + ) + _colorList ( rgbi:0.0/0.8/0.0 ) + _baseLabel "Free memory" + ) + + _stack 1 0 ( + _metrics ( + mem.util.kernel 98304 + mem.util.fs_ctl 98304 + mem.util.fs_dirty 98304 + mem.util.fs_clean 98304 + mem.util.user 98304 + ) + _colorList memory_colors + _baseLabel "Physical Memory Utilization\nNormalized to 98304 Kbytes" + ) +_baseColor rgbi:0.15/0.15/0.15 + ) + _label 3 1 2 1 north _medium "Mem" + +_marginWidth 8 +_marginDepth 8 +_baseHeight 2 + ) + + _grid 2 6 4 5 south _hide ( + _grid 0 0 1 2 west _hide ( + _label 0 0 east _right _medium "In" + _label 0 1 east _right _medium "Out" + ) +_marginWidth 4 +_marginDepth 4 +_baseHeight 4 + + _grid 1 0 2 2 _show ( +_baseColor rgbi:0.30/0.30/0.30 + + + _stack 0 0 ( + _metrics ( + network.interface.in.errors[ec0] 7 + network.interface.in.drops[ec0] 7 + network.interface.in.packets[ec0] 750 + ) + _colorList network_colors + _baseLabel "Input and Output on Network Interfaces\nPackets are normalized to 750 packets per second" + ) + _stack 0 1 ( + _metrics ( + network.interface.out.errors[ec0] 7 + network.interface.out.drops[ec0] 7 + network.interface.out.packets[ec0] 750 + ) + _colorList network_colors + _baseLabel "Input and Output on Network Interfaces\nPackets are normalized to 750 packets per second" + ) + + _stack 1 0 ( + _metrics ( + network.interface.in.errors[lo0] 7 + network.interface.in.drops[lo0] 7 + network.interface.in.packets[lo0] 750 + ) + _colorList network_colors + _baseLabel "Input and Output on Network Interfaces\nPackets are normalized to 750 packets per second" + ) + _stack 1 1 ( + _metrics ( + network.interface.out.errors[lo0] 7 + network.interface.out.drops[lo0] 7 + network.interface.out.packets[lo0] 750 + ) + _colorList network_colors + _baseLabel "Input and Output on Network Interfaces\nPackets are normalized to 750 packets per second" + ) + _baseLabel "Input and Output on Network Interfaces\nPackets are normalized to 750 packets per second" +_baseColor rgbi:0.15/0.15/0.15 + ) +_marginWidth 8 +_marginDepth 8 +_baseHeight 2 + _grid 1 2 2 2 _hide ( + _label 0 0 north _down _medium "ec0" + _label 1 0 north _down _medium "lo0" + ) + ) + _label 3 11 northwest _right _medium "Network" +) diff --git a/man/html/qwtlicense.html b/man/html/qwtlicense.html new file mode 100644 index 0000000..088b162 --- /dev/null +++ b/man/html/qwtlicense.html @@ -0,0 +1,572 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> +<HTML> +<HEAD> + <meta http-equiv="content-type" content="text/html; charset=utf-8"> + <meta http-equiv="content-style-type" content="text/css"> + <link href="pcpdoc.css" rel="stylesheet" type="text/css"> + <link href="images/pcp.ico" rel="icon" type="image/ico"> + <TITLE>PCP Manual</TITLE> +</HEAD> +<BODY LANG="en-AU" TEXT="#000060" DIR="LTR"> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 STYLE="page-break-before: always"> + <TR> <TD WIDTH=64 HEIGHT=64><A HREF="http://pcp.io/"><IMG SRC="images/pmcharticon.png" NAME="pmcharticon" ALIGN=TOP WIDTH=64 HEIGHT=64 BORDER=0></A></TD> + <TD WIDTH=1><P> </P></TD> + <TD WIDTH=500><P VALIGN=MIDDLE ALIGN=LEFT><A HREF="index.html"><FONT COLOR="#cc0000">Home</FONT></A> · <A HREF="lab.pmchart.html"><FONT COLOR="#cc0000">Charts</FONT></A> · <A HREF="timecontrol.html"><FONT COLOR="#cc0000">Time Control</FONT></A></P></TD> + </TR> +</TABLE> +<H1 ALIGN=CENTER STYLE="margin-top: 0.48cm; margin-bottom: 0.32cm"><FONT SIZE=7>QWT License (and LGPL)</FONT></H1> +<P>The <i>pmchart</i> and <i>pmtime</i> utilities makes extensive use of the <I>Qt Widgets for Technical applications</I> (QWT) library. QWT is Copyright (C) 1997 Josef Wilgen and Copyright (C) 2002 Uwe Rathman.</p> +<P>You may use, distribute and copy QWT under the terms of the QWT License version 1, which is displayed below.</P> + +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> Qwt License </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> Version 1.0, January 1, 2003 </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> The Qwt library and included programs are provided under the terms </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> of the GNU LESSER GENERAL PUBLIC LICENSE (LGPL) with the following </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> exceptions: </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> 1. Widgets that are subclassed from Qwt widgets do not </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> constitute a derivative work. </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> 2. Static linking of applications and widgets to the </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> Qwt library does not constitute a derivative work </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> and does not require the author to provide source </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> code for the application or widget, use the shared </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> Qwt libraries, or link their applications or </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> widgets against a user-supplied version of Qwt. </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> If you link the application or widget to a modified </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> version of Qwt, then the changes to Qwt must be </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> provided under the terms of the LGPL in sections </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> 1, 2, and 4. </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> 3. You do not have to provide a copy of the Qwt license </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> with programs that are linked to the Qwt library, nor </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> do you have to identify the Qwt license in your </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> program or documentation as required by section 6 </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> of the LGPL. </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> However, programs must still identify their use of Qwt. </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> The following example statement can be included in user </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> documentation to satisfy this requirement: </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> [program/widget] is based in part on the work of </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> the Qwt project (http://qwt.sf.net). </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> ---------------------------------------------------------------------- </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> GNU LESSER GENERAL PUBLIC LICENSE </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> Version 2.1, February 1999 </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> Copyright (C) 1991, 1999 Free Software Foundation, Inc. </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> 51 Franklin Street, Fifth Floor, Boston, MA 02110, USA </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> Everyone is permitted to copy and distribute verbatim copies </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> of this license document, but changing it is not allowed. </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> [This is the first released version of the Lesser GPL. It also counts </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> as the successor of the GNU Library Public License, version 2, hence </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> the version number 2.1.] </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> Preamble </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> The licenses for most software are designed to take away your </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> freedom to share and change it. By contrast, the GNU General Public </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> Licenses are intended to guarantee your freedom to share and change </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> free software--to make sure the software is free for all its users. </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> This license, the Lesser General Public License, applies to some </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> specially designated software packages--typically libraries--of the </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> Free Software Foundation and other authors who decide to use it. You </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> can use it too, but we suggest you first think carefully about whether </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> this license or the ordinary General Public License is the better </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> strategy to use in any particular case, based on the explanations below. </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> When we speak of free software, we are referring to freedom of use, </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> not price. Our General Public Licenses are designed to make sure that </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> you have the freedom to distribute copies of free software (and charge </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> for this service if you wish); that you receive source code or can get </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> it if you want it; that you can change the software and use pieces of </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> it in new free programs; and that you are informed that you can do </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> these things. </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> To protect your rights, we need to make restrictions that forbid </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> distributors to deny you these rights or to ask you to surrender these </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> rights. These restrictions translate to certain responsibilities for </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> you if you distribute copies of the library or if you modify it. </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> For example, if you distribute copies of the library, whether gratis </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> or for a fee, you must give the recipients all the rights that we gave </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> you. You must make sure that they, too, receive or can get the source </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> code. If you link other code with the library, you must provide </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> complete object files to the recipients, so that they can relink them </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> with the library after making changes to the library and recompiling </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> it. And you must show them these terms so they know their rights. </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> We protect your rights with a two-step method: (1) we copyright the </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> library, and (2) we offer you this license, which gives you legal </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> permission to copy, distribute and/or modify the library. </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> To protect each distributor, we want to make it very clear that </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> there is no warranty for the free library. Also, if the library is </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> modified by someone else and passed on, the recipients should know </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> that what they have is not the original version, so that the original </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> author's reputation will not be affected by problems that might be </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> introduced by others. </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> Finally, software patents pose a constant threat to the existence of </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> any free program. We wish to make sure that a company cannot </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> effectively restrict the users of a free program by obtaining a </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> restrictive license from a patent holder. Therefore, we insist that </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> any patent license obtained for a version of the library must be </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> consistent with the full freedom of use specified in this license. </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> Most GNU software, including some libraries, is covered by the </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> ordinary GNU General Public License. This license, the GNU Lesser </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> General Public License, applies to certain designated libraries, and </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> is quite different from the ordinary General Public License. We use </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> this license for certain libraries in order to permit linking those </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> libraries into non-free programs. </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> When a program is linked with a library, whether statically or using </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> a shared library, the combination of the two is legally speaking a </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> combined work, a derivative of the original library. The ordinary </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> General Public License therefore permits such linking only if the </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> entire combination fits its criteria of freedom. The Lesser General </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> Public License permits more lax criteria for linking other code with </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> the library. </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> We call this license the "Lesser" General Public License because it </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> does Less to protect the user's freedom than the ordinary General </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> Public License. It also provides other free software developers Less </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> of an advantage over competing non-free programs. These disadvantages </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> are the reason we use the ordinary General Public License for many </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> libraries. However, the Lesser license provides advantages in certain </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> special circumstances. </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> For example, on rare occasions, there may be a special need to </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> encourage the widest possible use of a certain library, so that it becomes </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> a de-facto standard. To achieve this, non-free programs must be </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> allowed to use the library. A more frequent case is that a free </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> library does the same job as widely used non-free libraries. In this </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> case, there is little to gain by limiting the free library to free </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> software only, so we use the Lesser General Public License. </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> In other cases, permission to use a particular library in non-free </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> programs enables a greater number of people to use a large body of </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> free software. For example, permission to use the GNU C Library in </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> non-free programs enables many more people to use the whole GNU </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> operating system, as well as its variant, the GNU/Linux operating </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> system. </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> Although the Lesser General Public License is Less protective of the </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> users' freedom, it does ensure that the user of a program that is </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> linked with the Library has the freedom and the wherewithal to run </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> that program using a modified version of the Library. </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> The precise terms and conditions for copying, distribution and </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> modification follow. Pay close attention to the difference between a </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> "work based on the library" and a "work that uses the library". The </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> former contains code derived from the library, whereas the latter must </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> be combined with the library in order to run. </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> GNU LESSER GENERAL PUBLIC LICENSE </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> 0. This License Agreement applies to any software library or other </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> program which contains a notice placed by the copyright holder or </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> other authorized party saying it may be distributed under the terms of </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> this Lesser General Public License (also called "this License"). </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> Each licensee is addressed as "you". </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> A "library" means a collection of software functions and/or data </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> prepared so as to be conveniently linked with application programs </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> (which use some of those functions and data) to form executables. </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> The "Library", below, refers to any such software library or work </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> which has been distributed under these terms. A "work based on the </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> Library" means either the Library or any derivative work under </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> copyright law: that is to say, a work containing the Library or a </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> portion of it, either verbatim or with modifications and/or translated </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> straightforwardly into another language. (Hereinafter, translation is </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> included without limitation in the term "modification".) </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> "Source code" for a work means the preferred form of the work for </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> making modifications to it. For a library, complete source code means </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> all the source code for all modules it contains, plus any associated </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> interface definition files, plus the scripts used to control compilation </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> and installation of the library. </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> Activities other than copying, distribution and modification are not </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> covered by this License; they are outside its scope. The act of </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> running a program using the Library is not restricted, and output from </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> such a program is covered only if its contents constitute a work based </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> on the Library (independent of the use of the Library in a tool for </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> writing it). Whether that is true depends on what the Library does </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> and what the program that uses the Library does. </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> 1. You may copy and distribute verbatim copies of the Library's </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> complete source code as you receive it, in any medium, provided that </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> you conspicuously and appropriately publish on each copy an </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> appropriate copyright notice and disclaimer of warranty; keep intact </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> all the notices that refer to this License and to the absence of any </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> warranty; and distribute a copy of this License along with the </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> Library. </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> You may charge a fee for the physical act of transferring a copy, </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> and you may at your option offer warranty protection in exchange for a </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> fee. </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> 2. You may modify your copy or copies of the Library or any portion </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> of it, thus forming a work based on the Library, and copy and </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> distribute such modifications or work under the terms of Section 1 </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> above, provided that you also meet all of these conditions: </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> a) The modified work must itself be a software library. </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> b) You must cause the files modified to carry prominent notices </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> stating that you changed the files and the date of any change. </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> c) You must cause the whole of the work to be licensed at no </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> charge to all third parties under the terms of this License. </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> d) If a facility in the modified Library refers to a function or a </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> table of data to be supplied by an application program that uses </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> the facility, other than as an argument passed when the facility </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> is invoked, then you must make a good faith effort to ensure that, </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> in the event an application does not supply such function or </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> table, the facility still operates, and performs whatever part of </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> its purpose remains meaningful. </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> (For example, a function in a library to compute square roots has </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> a purpose that is entirely well-defined independent of the </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> application. Therefore, Subsection 2d requires that any </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> application-supplied function or table used by this function must </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> be optional: if the application does not supply it, the square </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> root function must still compute square roots.) </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> These requirements apply to the modified work as a whole. If </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> identifiable sections of that work are not derived from the Library, </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> and can be reasonably considered independent and separate works in </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> themselves, then this License, and its terms, do not apply to those </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> sections when you distribute them as separate works. But when you </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> distribute the same sections as part of a whole which is a work based </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> on the Library, the distribution of the whole must be on the terms of </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> this License, whose permissions for other licensees extend to the </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> entire whole, and thus to each and every part regardless of who wrote </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> it. </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> Thus, it is not the intent of this section to claim rights or contest </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> your rights to work written entirely by you; rather, the intent is to </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> exercise the right to control the distribution of derivative or </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> collective works based on the Library. </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> In addition, mere aggregation of another work not based on the Library </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> with the Library (or with a work based on the Library) on a volume of </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> a storage or distribution medium does not bring the other work under </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> the scope of this License. </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> 3. You may opt to apply the terms of the ordinary GNU General Public </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> License instead of this License to a given copy of the Library. To do </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> this, you must alter all the notices that refer to this License, so </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> that they refer to the ordinary GNU General Public License, version 2, </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> instead of to this License. (If a newer version than version 2 of the </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> ordinary GNU General Public License has appeared, then you can specify </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> that version instead if you wish.) Do not make any other change in </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> these notices. </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> Once this change is made in a given copy, it is irreversible for </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> that copy, so the ordinary GNU General Public License applies to all </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> subsequent copies and derivative works made from that copy. </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> This option is useful when you wish to copy part of the code of </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> the Library into a program that is not a library. </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> 4. You may copy and distribute the Library (or a portion or </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> derivative of it, under Section 2) in object code or executable form </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> under the terms of Sections 1 and 2 above provided that you accompany </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> it with the complete corresponding machine-readable source code, which </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> must be distributed under the terms of Sections 1 and 2 above on a </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> medium customarily used for software interchange. </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> If distribution of object code is made by offering access to copy </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> from a designated place, then offering equivalent access to copy the </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> source code from the same place satisfies the requirement to </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> distribute the source code, even though third parties are not </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> compelled to copy the source along with the object code. </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> 5. A program that contains no derivative of any portion of the </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> Library, but is designed to work with the Library by being compiled or </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> linked with it, is called a "work that uses the Library". Such a </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> work, in isolation, is not a derivative work of the Library, and </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> therefore falls outside the scope of this License. </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> However, linking a "work that uses the Library" with the Library </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> creates an executable that is a derivative of the Library (because it </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> contains portions of the Library), rather than a "work that uses the </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> library". The executable is therefore covered by this License. </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> Section 6 states terms for distribution of such executables. </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> When a "work that uses the Library" uses material from a header file </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> that is part of the Library, the object code for the work may be a </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> derivative work of the Library even though the source code is not. </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> Whether this is true is especially significant if the work can be </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> linked without the Library, or if the work is itself a library. The </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> threshold for this to be true is not precisely defined by law. </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> If such an object file uses only numerical parameters, data </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> structure layouts and accessors, and small macros and small inline </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> functions (ten lines or less in length), then the use of the object </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> file is unrestricted, regardless of whether it is legally a derivative </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> work. (Executables containing this object code plus portions of the </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> Library will still fall under Section 6.) </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> Otherwise, if the work is a derivative of the Library, you may </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> distribute the object code for the work under the terms of Section 6. </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> Any executables containing that work also fall under Section 6, </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> whether or not they are linked directly with the Library itself. </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> 6. As an exception to the Sections above, you may also combine or </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> link a "work that uses the Library" with the Library to produce a </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> work containing portions of the Library, and distribute that work </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> under terms of your choice, provided that the terms permit </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> modification of the work for the customer's own use and reverse </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> engineering for debugging such modifications. </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> You must give prominent notice with each copy of the work that the </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> Library is used in it and that the Library and its use are covered by </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> this License. You must supply a copy of this License. If the work </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> during execution displays copyright notices, you must include the </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> copyright notice for the Library among them, as well as a reference </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> directing the user to the copy of this License. Also, you must do one </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> of these things: </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> a) Accompany the work with the complete corresponding </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> machine-readable source code for the Library including whatever </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> changes were used in the work (which must be distributed under </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> Sections 1 and 2 above); and, if the work is an executable linked </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> with the Library, with the complete machine-readable "work that </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> uses the Library", as object code and/or source code, so that the </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> user can modify the Library and then relink to produce a modified </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> executable containing the modified Library. (It is understood </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> that the user who changes the contents of definitions files in the </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> Library will not necessarily be able to recompile the application </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> to use the modified definitions.) </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> b) Use a suitable shared library mechanism for linking with the </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> Library. A suitable mechanism is one that (1) uses at run time a </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> copy of the library already present on the user's computer system, </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> rather than copying library functions into the executable, and (2) </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> will operate properly with a modified version of the library, if </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> the user installs one, as long as the modified version is </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> interface-compatible with the version that the work was made with. </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> c) Accompany the work with a written offer, valid for at </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> least three years, to give the same user the materials </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> specified in Subsection 6a, above, for a charge no more </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> than the cost of performing this distribution. </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> d) If distribution of the work is made by offering access to copy </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> from a designated place, offer equivalent access to copy the above </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> specified materials from the same place. </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> e) Verify that the user has already received a copy of these </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> materials or that you have already sent this user a copy. </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> For an executable, the required form of the "work that uses the </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> Library" must include any data and utility programs needed for </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> reproducing the executable from it. However, as a special exception, </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> the materials to be distributed need not include anything that is </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> normally distributed (in either source or binary form) with the major </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> components (compiler, kernel, and so on) of the operating system on </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> which the executable runs, unless that component itself accompanies </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> the executable. </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> It may happen that this requirement contradicts the license </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> restrictions of other proprietary libraries that do not normally </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> accompany the operating system. Such a contradiction means you cannot </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> use both them and the Library together in an executable that you </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> distribute. </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> 7. You may place library facilities that are a work based on the </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> Library side-by-side in a single library together with other library </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> facilities not covered by this License, and distribute such a combined </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> library, provided that the separate distribution of the work based on </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> the Library and of the other library facilities is otherwise </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> permitted, and provided that you do these two things: </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> a) Accompany the combined library with a copy of the same work </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> based on the Library, uncombined with any other library </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> facilities. This must be distributed under the terms of the </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> Sections above. </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> b) Give prominent notice with the combined library of the fact </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> that part of it is a work based on the Library, and explaining </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> where to find the accompanying uncombined form of the same work. </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> 8. You may not copy, modify, sublicense, link with, or distribute </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> the Library except as expressly provided under this License. Any </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> attempt otherwise to copy, modify, sublicense, link with, or </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> distribute the Library is void, and will automatically terminate your </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> rights under this License. However, parties who have received copies, </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> or rights, from you under this License will not have their licenses </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> terminated so long as such parties remain in full compliance. </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> 9. You are not required to accept this License, since you have not </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> signed it. However, nothing else grants you permission to modify or </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> distribute the Library or its derivative works. These actions are </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> prohibited by law if you do not accept this License. Therefore, by </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> modifying or distributing the Library (or any work based on the </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> Library), you indicate your acceptance of this License to do so, and </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> all its terms and conditions for copying, distributing or modifying </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> the Library or works based on it. </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> 10. Each time you redistribute the Library (or any work based on the </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> Library), the recipient automatically receives a license from the </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> original licensor to copy, distribute, link with or modify the Library </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> subject to these terms and conditions. You may not impose any further </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> restrictions on the recipients' exercise of the rights granted herein. </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> You are not responsible for enforcing compliance by third parties with </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> this License. </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> 11. If, as a consequence of a court judgment or allegation of patent </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> infringement or for any other reason (not limited to patent issues), </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> conditions are imposed on you (whether by court order, agreement or </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> otherwise) that contradict the conditions of this License, they do not </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> excuse you from the conditions of this License. If you cannot </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> distribute so as to satisfy simultaneously your obligations under this </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> License and any other pertinent obligations, then as a consequence you </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> may not distribute the Library at all. For example, if a patent </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> license would not permit royalty-free redistribution of the Library by </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> all those who receive copies directly or indirectly through you, then </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> the only way you could satisfy both it and this License would be to </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> refrain entirely from distribution of the Library. </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> If any portion of this section is held invalid or unenforceable under any </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> particular circumstance, the balance of the section is intended to apply, </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> and the section as a whole is intended to apply in other circumstances. </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> It is not the purpose of this section to induce you to infringe any </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> patents or other property right claims or to contest validity of any </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> such claims; this section has the sole purpose of protecting the </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> integrity of the free software distribution system which is </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> implemented by public license practices. Many people have made </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> generous contributions to the wide range of software distributed </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> through that system in reliance on consistent application of that </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> system; it is up to the author/donor to decide if he or she is willing </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> to distribute software through any other system and a licensee cannot </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> impose that choice. </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> This section is intended to make thoroughly clear what is believed to </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> be a consequence of the rest of this License. </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> 12. If the distribution and/or use of the Library is restricted in </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> certain countries either by patents or by copyrighted interfaces, the </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> original copyright holder who places the Library under this License may add </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> an explicit geographical distribution limitation excluding those countries, </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> so that distribution is permitted only in or among countries not thus </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> excluded. In such case, this License incorporates the limitation as if </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> written in the body of this License. </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> 13. The Free Software Foundation may publish revised and/or new </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> versions of the Lesser General Public License from time to time. </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> Such new versions will be similar in spirit to the present version, </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> but may differ in detail to address new problems or concerns. </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> Each version is given a distinguishing version number. If the Library </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> specifies a version number of this License which applies to it and </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> "any later version", you have the option of following the terms and </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> conditions either of that version or of any later version published by </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> the Free Software Foundation. If the Library does not specify a </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> license version number, you may choose any version ever published by </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> the Free Software Foundation. </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> 14. If you wish to incorporate parts of the Library into other free </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> programs whose distribution conditions are incompatible with these, </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> write to the author to ask for permission. For software which is </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> copyrighted by the Free Software Foundation, write to the Free </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> Software Foundation; we sometimes make exceptions for this. Our </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> decision will be guided by the two goals of preserving the free status </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> of all derivatives of our free software and of promoting the sharing </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> and reuse of software generally. </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> NO WARRANTY </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> 15. BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW. </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> OTHER PARTIES PROVIDE THE LIBRARY "AS IS" WITHOUT WARRANTY OF ANY </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> LIBRARY IS WITH YOU. SHOULD THE LIBRARY PROVE DEFECTIVE, YOU ASSUME </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> 16. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE LIABLE TO YOU </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> DAMAGES. </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> END OF TERMS AND CONDITIONS </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> How to Apply These Terms to Your New Libraries </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> If you develop a new library, and you want it to be of the greatest </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> possible use to the public, we recommend making it free software that </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> everyone can redistribute and change. You can do so by permitting </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> redistribution under these terms (or, alternatively, under the terms of the </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> ordinary General Public License). </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> To apply these terms, attach the following notices to the library. It is </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> safest to attach them to the start of each source file to most effectively </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> convey the exclusion of warranty; and each file should have at least the </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> "copyright" line and a pointer to where the full notice is found. </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> <one line to give the library's name and a brief idea of what it does.> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> Copyright (C) <year> <name of author> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> This library is free software; you can redistribute it and/or </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> modify it under the terms of the GNU Lesser General Public </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> License as published by the Free Software Foundation; either </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> version 2.1 of the License, or (at your option) any later version. </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> This library is distributed in the hope that it will be useful, </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> but WITHOUT ANY WARRANTY; without even the implied warranty of </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> Lesser General Public License for more details. </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> You should have received a copy of the GNU Lesser General Public </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> License along with this library; if not, write to the Free Software </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110, USA </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> Also add information on how to contact you by electronic and paper mail. </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> You should also get your employer (if you work as a programmer) or your </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> school, if any, to sign a "copyright disclaimer" for the library, if </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> necessary. Here is a sample; alter the names: </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> Yoyodyne, Inc., hereby disclaims all copyright interest in the </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> library `Frob' (a library for tweaking knobs) written by James Random Hacker. </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> <signature of Ty Coon>, 1 April 1990 </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> Ty Coon, President of Vice </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> </pre> +<pre style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-family:'Courier New,courier'; color:#000000; background-color:#f1f1f1;" bgcolor="#f1f1f1"> That's all there is to it! </pre> + +<P><BR></P> +<HR> +<CENTER> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0> + <TR> <TD WIDTH=50%><P>Copyright © 2007-2010 <A HREF="http://www.aconex.com/"><FONT COLOR="#000060">Aconex</FONT></A><BR>Copyright © 2000-2004 <A HREF="http://www.sgi.com/"><FONT COLOR="#000060">Silicon Graphics Inc</FONT></P></TD> + <TD WIDTH=50%><P ALIGN=RIGHT><A HREF="http://pcp.io/"><FONT COLOR="#000060">PCP Site</FONT></A><BR>Copyright © 2012-2014 <A HREF="http://www.redhat.com/"><FONT COLOR="#000060">Red Hat</FONT></P></TD> </TR> +</TABLE> +</CENTER> +</BODY> +</HTML> diff --git a/man/html/timecontrol.html b/man/html/timecontrol.html new file mode 100644 index 0000000..fc500c7 --- /dev/null +++ b/man/html/timecontrol.html @@ -0,0 +1,69 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> +<HTML> +<HEAD> + <meta http-equiv="content-type" content="text/html; charset=utf-8"> + <meta http-equiv="content-style-type" content="text/css"> + <link href="pcpdoc.css" rel="stylesheet" type="text/css"> + <link href="images/pcp.ico" rel="icon" type="image/ico"> + <TITLE>Time Control</TITLE> +</HEAD> +<BODY LANG="en-AU" TEXT="#000060" DIR="LTR"> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 STYLE="page-break-before: always"> + <TR> <TD WIDTH=64 HEIGHT=64><A HREF="http://pcp.io/"><IMG SRC="images/pmtimeicon.png" NAME="pmtimeicon" ALIGN=TOP WIDTH=64 HEIGHT=64 BORDER=0></A></TD> + <TD WIDTH=1><P> </P></TD> + <TD WIDTH=500><P VALIGN=MIDDLE ALIGN=LEFT><A HREF="index.html"><FONT COLOR="#cc0000">Home</FONT></A> · <A HREF="lab.pmchart.html"><FONT COLOR="#cc0000">Charts</FONT></A> · <A HREF="timecontrol.html"><FONT COLOR="#cc0000">Time Control</FONT></A></P></TD> + </TR> +</TABLE> +<H1 ALIGN=CENTER STYLE="margin-top: 0.48cm; margin-bottom: 0.32cm"><FONT SIZE=7>Time Control</FONT></H1> +<P>The graphical time control utility, <I>pmtime</I>, is used to coordinate all aspects of time synchonisation in <I>pmchart</I>. Most importantly, this means the current sample time is set by <I>pmtime</I>, but also includes things like the update delta, update speed, and the timezone. It presents a VCR model which can be used to stop time, play forwards, rewind, and fast forward through time. +</P> +<P><BR></P> + +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 BGCOLOR="#e2e2e2"> + <TR><TD WIDTH=100% BGCOLOR="#081c59"><P ALIGN=LEFT><FONT SIZE=5 COLOR="#ffffff"><B>Main Window</B></FONT></P></TD></TR> +</TABLE> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 STYLE="page-break-before: always"> + <TR><TD><P><BR><I>pmtime</I> operates in either live or archive mode, depending on the data source. In archive mode, there is additional functionality available, as both forward and backward movement is possible, and it is can speed up or slow down the time updates relative to real time. Some functionality is common between the two modes, however. The sample interval (and units) can always be set using the <I>Interval</I>. The current time position is always displayed in the <I>Position</I> text box (this equates to the rightmost time point in the <I>pmchart</I> window). And when hosts or archives from different timezones to the monitoring host are used, a drop-down list of available timezones is available from the options menu, which allows you to change the reporting timezone in the monitoring tools (this always defaults to localtime on the monitoring host - <B>not</B> the monitored host).</P> + <TD WIDTH=456><P VALIGN=MIDDLE ALIGN=RIGHT><CENTER><BR><IMG ALIGN=RIGHT SRC="images/pmtime_clients.png" BORDER=0></CENTER></P></TD> +</TABLE> +<P><I>pmtime</I> can actually coordinate the flow of time to multiple client programs. For example, if a second <I>pmchart</I> is started via the <I>Options</I> menu, it will share the time control process with the original <I>pmchart</I> and both will be updated in lock-step. This is true for both Live and Archive monitoring, and there is even support for controlling time for other PCP clients (like <I>pmval</I>) as well.</P> +<BR> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 BGCOLOR="#e2e2e2"> + <TR><TD WIDTH=100% BGCOLOR="#081c59"><P ALIGN=LEFT><FONT SIZE=5 COLOR="#ffffff"><B>Live Mode</B></FONT></P></TD></TR> +</TABLE> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 STYLE="page-break-before: always"> + <TR><TD WIDTH=350><P VALIGN=MIDDLE ALIGN=LEFT><CENTER><BR><IMG ALIGN=LEFT SRC="images/pmtime_live.png" BORDER=0></CENTER></P></TD> + <TD><BR><P>There are just two states available in live mode:<UL><LI>Playing, where time updates are sent to the client at a continuous rate in real time. + <LI>Stopped, where time is frozen at a particular point in time. +</UL></P> + </TR> +</TABLE> +</P> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 BGCOLOR="#e2e2e2"> + <TR><TD WIDTH=100% BGCOLOR="#081c59"><P ALIGN=LEFT><FONT SIZE=5 COLOR="#ffffff"><B>Archive Mode</B></FONT></P></TD></TR> +</TABLE> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 STYLE="page-break-before: always"> + <TR><TD WIDTH=350><P VALIGN=MIDDLE ALIGN=LEFT><CENTER><BR><IMG ALIGN=LEFT SRC="images/pmtime_archive.png" BORDER=0></CENTER></P></TD> + <TD><BR><P>There are several modes of playback available in archive mode:<UL><LI>Normal mode, where time updates are sent to the client at a continuous rate (usually not too different to the original live recording), as determined by the "Speed" wheel setting. + <LI>Step mode, where time is only advanced/retreated (by clicking on the Step button) one sample at a time. + <LI>Fast mode, where time is moved quickly in either a fast forward or fast rewind direction, and the visible charts are updated as quickly as possible. +</UL></P><P>The Speed setting can be changed by directly editing the text entry box, or more simply by selecting and rotating the wheel either left or right. Speed is only relevent in Normal mode.</TD> + </TR> +</TABLE> +<P>In archive mode, the <I>Position</I> text box is editable, and any valid PCP timestamp can be entered here. Alternatively, and more simply, the archive mode provides a slider beneath the <I>Position</I> text box allowing the time position to be set directly using the pointing device (click, drag, and release at the desired time position). +</P> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 STYLE="page-break-before: always"> + <TR><TD><BR><P>One last feature specific to archive mode, is the <I>Time Bounds</I> dialog. This window, available from the <I>Options</I> menu, displays the start and end position for all archives presented to <I>pmchart</I> (and hence <I>pmtime</I>). The editable <I>Start</I> and <I>End</I> position text boxes (and associated sliders) allow the time updates to be restricted to a specific time range. Once archive play/rewind hits these caliper points, replay will stop (independent of whether that is the start or end of the archive). This allows for a fine-grained level of focus around particular performance events.</TD> + <TD WIDTH=350><P VALIGN=MIDDLE ALIGN=RIGHT><CENTER><BR><IMG ALIGN=RIGHT SRC="images/pmtime_bounds.png" BORDER=0></CENTER></P></TD> + </TR> +</TABLE> +<P><BR></P> +<HR> +<CENTER> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0> + <TR> <TD WIDTH=50%><P>Copyright © 2007-2010 <A HREF="http://www.aconex.com/"><FONT COLOR="#000060">Aconex</FONT></A><BR>Copyright © 2000-2004 <A HREF="http://www.sgi.com/"><FONT COLOR="#000060">Silicon Graphics Inc</FONT></P></TD> + <TD WIDTH=50%><P ALIGN=RIGHT><A HREF="http://pcp.io/"><FONT COLOR="#000060">PCP Site</FONT></A><BR>Copyright © 2012-2014 <A HREF="http://www.redhat.com/"><FONT COLOR="#000060">Red Hat</FONT></P></TD> </TR> +</TABLE> +</CENTER> +</BODY> +</HTML> diff --git a/man/html/views.html b/man/html/views.html new file mode 100644 index 0000000..5ce9ca2 --- /dev/null +++ b/man/html/views.html @@ -0,0 +1,89 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> +<HTML> +<HEAD> + <meta http-equiv="content-type" content="text/html; charset=utf-8"> + <meta http-equiv="content-style-type" content="text/css"> + <link href="pcpdoc.css" rel="stylesheet" type="text/css"> + <link href="images/pcp.ico" rel="icon" type="image/ico"> + <TITLE>Chart Views</TITLE> +</HEAD> +<BODY LANG="en-AU" TEXT="#000060" DIR="LTR"> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 STYLE="page-break-before: always"> + <TR> <TD WIDTH=64 HEIGHT=64><A HREF="http://pcp.io/"><IMG SRC="images/pmcharticon.png" NAME="pmcharticon" ALIGN=TOP WIDTH=64 HEIGHT=64 BORDER=0></A></TD> + <TD WIDTH=1><P> </P></TD> + <TD WIDTH=500><P VALIGN=MIDDLE ALIGN=LEFT><A HREF="index.html"><FONT COLOR="#cc0000">Home</FONT></A> · <A HREF="lab.pmchart.html"><FONT COLOR="#cc0000">Charts</FONT></A> · <A HREF="timecontrol.html"><FONT COLOR="#cc0000">Time Control</FONT></A></P></TD> + </TR> +</TABLE> +<H1 ALIGN=CENTER STYLE="margin-top: 0.48cm; margin-bottom: 0.32cm"><FONT SIZE=7>Views</FONT></H1> +<P>The primary pmchart configuration file is the "view", which allows the metadata associated with one or more charts to be saved in the filesystem. This metadata describes all aspects of the charts, including which PCP metrics and instances are to be used, which hosts, which colors, the chart titles, use of chart legends, and much more. +<P>From a conceptual point of view, there are two classes of view. These views share the same configuration file format, described below. The differences lie in where they are installed and how they are manipulated. +<P>The first class, the "system" view, is simply any view that is installed as part of the pmchart package. These are stored in <I>$PCP_VAR_DIR/config/pmchart</I>. When the <I>File→Open View</I> dialog is displayed, it is these views that are initially listed. The system views cannot be modified by a normal user, and should not be modified even by a user with suitable priviledges, as they will be overwritten during an upgrade. +<P>The second class of view is the "user" view. These views are created on-the-fly using the <I>File→Save View</I> dialog. This is a mechanism for individual users to save their commonly used views. Access to these views is achieved through the <I>File→Open View</I> dialog, as with the system views. Once the dialog is opened, the list of views can be toggled between user and system views by clicking on the two toggle buttons in the top right corner. User views are stored in <I>$HOME/.pcp/pmchart</I>. +<P> </P> +<P>The current pmchart configuration file syntax has <A HREF="pmchart.html">evolved</A> from the original SGI pmchart syntax. +<P> </P> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0 BGCOLOR="#e2e2e2"> + <TR><TD WIDTH=100% BGCOLOR="#081c59"><P ALIGN=LEFT><FONT SIZE=5 COLOR="#ffffff"><B>Configuration File Syntax</B></FONT></P></TD></TR> +</TABLE> +<P>pmchart loads predefined chart configurations (or "views") from external files that conform to the following rules. In the descriptions below keywords (shown in bold) may appear in upper, lower or mixed case, elements shown as [stuff] are optional, and user-supplied elements are shown as <other stuff>. A vertical bar (|) is used where syntactic elements are alternatives. Quotes (") may be used to enclose lexical elements that may contain white space, such as titles, labels and instance names. +<P><OL> + <LI>The first line defines the configuration file type and should be +<PRE> #kmchart</PRE> +although pmchart provides backwards compatibility for original SGI pmchart formats with an initial line of +<PRE> #pmchart</PRE> + <LI>After the first line, lines beginning with "#" as the first non-whitespace character are treated as comments and skipped. Similarly blank lines are skipped.<PRE></PRE> + <LI>The next line should be +<PRE> version <n> <host-clause></PRE> +where <n> depends on the configuration file type, and is 1 for kmchart else 1.1, 1.2 or 2.0 for pmchart. +<BR>The <host-clause> part is optional (and ignored) for pmchart configuration files, but required for the older pmchart configuration files, and is of the form +<PRE> host literal</PRE> +or +<PRE> host dynamic</PRE> + <LI>A configuration contains one or more charts defined as follows: +<PRE> chart [title <title>] style <style> <options></PRE> +If specified, the title will appear centred and above the graph area of the chart. The <title> is usually enclosed in quotes (") and if it contains the sequence "%h" this will be replaced by the short form of the hostname for the default source of metrics at the time this chart was loaded. After the view is loaded, the title visibility and setting can be manipulated using the Chart Title text box in the <I>Edit→Chart</I> dialog. +<BR>The <options> are zero or more of the optional elements: +<PRE> [scale [from] <ymin> [to] <ymax>] [legend <onoff>]</PRE> +If <B>scale</B> is specified, the vertical scaling is set for all plots in the chart to a y-range defined by <ymin> and <ymax>. Otherwise the vertical axis will be autoscaled based on the values currently being plotted. +<BR><onoff> is one of the keywords <B>on</B> or <B>off</B> and the <B>legend</B> clause controls the presence or absence of the plot legend below the graph area. The default is for the legend to be shown. After the view is loaded, the legend visibility can be toggled using the Show Legend button in the <I>Edit→Chart</I> dialog.<PRE></PRE> + <LI>pmchart supports a <B>global</B> clause to specify the dimensions of the top-level window (using the <B>width</B> and <B>height</B> keywords), the number of visible points (<B>points</B> keyword) and the starting X and Y axis positions on the screen (<B>xpos</B> and <B>ypos</B> keywords). Each of these global attributes takes an integer value as the sole qualifier.<PRE></PRE> + <LI>Each chart has one or more plots associated with it, as defined by one of the following specifications: +<PRE> plot + [legend <title>] [color <colorspec>] [host <hostspec>] + metric <metricname> + [ instance <inst> | matching <pat> | not-matching <pat> ]</PRE> +The keyword <B>plot</B> may be replaced with the keyword <B>optional-plot</B>, in which case if the source of performance data does not include the specified performance metric and/or instance, then this plot is silently dropped from the chart. +<BR>If specified, the title will appear in the chart legend. The <title> is usually enclosed in quotes (") and if it contains the sequence "%i" this will be replaced by the metric instance name (if any). +<P>For pmchart configuration files, the keyword <B>title</B> must be used instead of <B>legend</B>. pmchart supports either keyword. +<BR>The <B>color</B> clause is optional for new pmchart configuration files, but it is mandatory for older pmchart configuration files. <colorspec> may be one of the following: +<PRE> #-cycle<BR> + rgbi:rr:gg:bb<BR> + #rgb<BR> + #rrggbb<BR> + #rrrgggbbb<BR> + #rrrrggggbbbb<BR> + <Xcolor></PRE> +where each of r, g and b are hexidecimal digits (0-9 and A-F) representing respectively the red, green and blue color components. <Xcolor> is one of the color names from the X color database, e.g. red or steelblue, see also the output from <B>showrgb</B>(1) on X11 platforms. +<BR>The "color" #-cycle specifies that pmchart should use the next in a pallet of colors that it uses cyclically for each chart. This is the default if the <B>color</B> clause is omitted. +<BR>The <hostspec> in the <B>host</B> clause may be a hostname, an IP address or an asterisk (*); the latter is used to mean the default source of performance metrics. For pmchart configuration files, the <B>host</B> clause must be present, for new pmchart configuration files it is optional, and if missing the default source of performance metrics will be used. +<BR>The optional <B>instance</B> specification, + <OL><LI>is omitted in which case one plot will be created for every instance of the <metricname> metric + <LI>starts with <B>instance</B>, in which case only the instance named <inst> will be plotted + <LI>starts with <B>matching</B>, in which case all instances whose names match the pattern <pat> will be plotted; the pattern uses extended regular expression notation in the style of <B>egrep</B>(1) (refer to the <I>PMCD</I> view for an example) + <LI>starts with <B>not-matching</B>, in which case all instances whose names do not match the pattern <pat> will be plotted; the pattern uses extended regular expression notation in the style of <B>egrep</B>(1) (refer to the <I>Netbytes</I> view for an example) +<BR>The original pmchart syntax uses a bizarre notation where <inst> and <pat> extend from the first non-white space character to the end of the input line. For modern pmchart configuration files these elements are either delimited by white space, or enclosed in quotes ("). +</OL><PRE></PRE> + <LI>The optional <B>tab</B> directive can be used to create views with multiple charts which span multiple Tabs. The synax is as follows: +<PRE> tab <label> [host <host>] [points <points> [samples <samples>]]</PRE> +<BR>All chart specifications following this keyword will be created on the new Tab, until the end of the configuration file or until another <B>tab</B> keyword is encountered. +</OL> +<P> </P> +<HR> +<CENTER> +<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0> + <TR> <TD WIDTH=50%><P>Copyright © 2007-2010 <A HREF="http://www.aconex.com/"><FONT COLOR="#000060">Aconex</FONT></A><BR>Copyright © 2000-2004 <A HREF="http://www.sgi.com/"><FONT COLOR="#000060">Silicon Graphics Inc</FONT></P></TD> + <TD WIDTH=50%><P ALIGN=RIGHT><A HREF="http://pcp.io/"><FONT COLOR="#000060">PCP Site</FONT></A><BR>Copyright © 2012-2014 <A HREF="http://www.redhat.com/"><FONT COLOR="#000060">Red Hat</FONT></P></TD> </TR> +</TABLE> +</CENTER> +</BODY> +</HTML> diff --git a/man/man1/GNUmakefile b/man/man1/GNUmakefile new file mode 100644 index 0000000..c8c863c --- /dev/null +++ b/man/man1/GNUmakefile @@ -0,0 +1,103 @@ +# +# Copyright (c) 2012-2014 Red Hat. +# Copyright (c) 2000,2004 Silicon Graphics, Inc. All Rights Reserved. +# +# This program is free software; you can redistribute it and/or modify it +# under the terms of the GNU General Public License as published by the +# Free Software Foundation; either version 2 of the License, or (at your +# option) any later version. +# +# This program is distributed in the hope that it will be useful, but +# WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +# or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +# for more details. +# + +TOPDIR = ../.. +include $(TOPDIR)/src/include/builddefs +-include ./GNUlocaldefs + +MAN_SECTION = 1 + +MAN_PAGES = \ + chkhelp.1 dbpmda.1 mkaf.1 newhelp.1 pcp.1 pcpintro.1 pmafm.1 \ + pmcd.1 pmcd_wait.1 pmclient.1 pmconfig.1 pmdbg.1 pmdumplog.1 \ + pmerr.1 pmgenmap.1 pmhostname.1 pmie.1 pmie_check.1 pminfo.1 \ + pmlc.1 pmlock.1 pmlogcheck.1 pmlogconf.1 pmlogextract.1 \ + pmlogger.1 pmlogger_check.1 pmnewlog.1 pmnsadd.1 pmnsdel.1 \ + pmnsmerge.1 pmpost.1 pmprobe.1 pmsocks.1 pmstat.1 pmstore.1 \ + pmtrace.1 pmval.1 pmlogsummary.1 pmdate.1 pmlogmv.1 \ + pmloglabel.1 genpmda.1 pmproxy.1 pmlogreduce.1 \ + autofsd-probe.1 pmie2col.1 telnet-probe.1 pmsleep.1 pmsignal.1 \ + pmieconf.1 pmiestatus.1 pmevent.1 pmcpp.1 pmlogrewrite.1 \ + pmatop.1 pmcollectl.1 pmdiff.1 collectl2pcp.1 pmmgr.1 pmfind.1 \ + pmchart.1 pmdumptext.1 pmquery.1 pmsnap.1 pmtime.1 \ + \ + pmdaapache.1 pmdabash.1 pmdacisco.1 \ + pmdadmcache.1 pmdagfs2.1 pmdagluster.1 \ + pmdakernel.1 \ + pmdalogger.1 pmdamailq.1 pmdammv.1 pmdamounts.1 pmdanvidia.1 \ + pmdasample.1 pmdasendmail.1 pmdashping.1 pmdasimple.1 \ + pmdasummary.1 \ + pmdatrace.1 pmdatrivial.1 pmdatxmon.1 pmdaweblog.1 \ + pmdazswap.1 pmiostat.1 + +LINUX_PMDA_PAGES = \ + pmdalmsensors.1 pmdalustrecomm.1 pmdaproc.1 pmdaxfs.1 pmdajbd2.1 +ROOMTEMP_PMDA_PAGES = pmdaroomtemp.1 +SYSTEMD_PMDA_PAGES = pmdasystemd.1 +RPM_PMDA_PAGES = pmdarpm.1 +IB_PMDA_PAGES = pmdaib.1 +WEBD_PAGES = pmwebd.1 +PAPI_PMDA_PAGES = pmdapapi.1 + +ifeq "$(TARGET_OS)" "linux" +MAN_PAGES += $(LINUX_PMDA_PAGES) +else +OTHER_PAGES += $(LINUX_PMDA_PAGES) +endif +ifneq "$(findstring $(TARGET_OS),solaris linux)" "" +MAN_PAGES += $(ROOMTEMP_PMDA_PAGES) +else +OTHER_PAGES += $(ROOMTEMP_PMDA_PAGES) +endif +ifeq "$(HAVE_RPMLIB)" "1" +MAN_PAGES += $(RPM_PMDA_PAGES) +else +OTHER_PAGES += $(RPM_PMDA_PAGES) +endif +ifneq "$(PMDA_SYSTEMD)" "" +MAN_PAGES += $(SYSTEMD_PMDA_PAGES) +else +OTHER_PAGES += $(SYSTEMD_PMDA_PAGES) +endif +ifneq "$(PMDA_INFINIBAND)" "" +MAN_PAGES += $(IB_PMDA_PAGES) +else +OTHER_PAGES += $(IB_PMDA_PAGES) +endif +ifeq "$(HAVE_LIBMICROHTTPD)" "1" +MAN_PAGES += $(WEBD_PAGES) +else +OTHER_PAGES += $(WEBD_PAGES) +endif +ifneq "$(ENABLE_PAPI)" "" +MAN_PAGES += $(PAPI_PMDA_PAGES) +else +OTHER_PAGES += $(PAPI_PMDA_PAGES) +endif + + +MAN_DEST = $(PCP_MAN_DIR)/man$(MAN_SECTION) +LSRCFILES = $(MAN_PAGES) $(OTHER_PAGES) + +default :: default_pcp + +default_pcp : $(MAN_PAGES) + +install :: install_pcp + +install_pcp : default_pcp + @MAN_PAGES="$(MAN_PAGES)"; $(INSTALL_MAN) + +include $(BUILDRULES) diff --git a/man/man1/autofsd-probe.1 b/man/man1/autofsd-probe.1 new file mode 100644 index 0000000..5f7a415 --- /dev/null +++ b/man/man1/autofsd-probe.1 @@ -0,0 +1,85 @@ +'\"macro stdmacro +.TH AUTOFSD-PROBE 1 "PCP" "Performance Co-Pilot" +.SH NAME +\f3autofsd-probe\f1 \- probe AutoFS mount/unmount daemon +.SH SYNOPSIS +\f3$PCP_BINADM_DIR/autofsd-probe\f1 +[\f3\-h\f1 \f2host\f1] +[\f3\-t\f1 \f2timeout\f1] +.SH DESCRIPTION +.B autofsd-probe +will check the status of the +.BR autofsd (1) +daemon on the specified +.IR host . +.PP +Unless directed to another +.I host +by the +.B \-h +option, +.B autofsd-probe +will contact the +.B AutoFS +daemon on the local host. +.PP +The +.B AutoFS +file system is built on the Remote Procedure Call (\c +.BR RPC (3)) +library routines. The +.B \-t +option allows the total timeout and retry timeout intervals to be set for all +remote procedure call operations used with +.BR autofsd-probe . +This option accepts an interval argument in the form described in the +.BR PCPintro (1) +manual page. +.PP +.B autofsd-probe +is typically used in an automated fashion from within +.BR pmdashping (1) +and in conjunction with +.BR pmie (1), +for monitoring response time and service failure. +.PP +By default +.B autofsd-probe +will not produce any output, unless there is an error in which case +a diagnostic message will be displayed and the exit status will indicate +the reason for failure. +.SH DIAGNOSTICS +If +.B autofsd-probe +succeeds, then 0 will be returned. +If the attempt to establish a connection with +.B autofsd +fails, then 2 is returned. +If the subsequent attempt to invoke an +.B autofsd +response fails, then 1 will be returned. +.PP +In the case of a syntactical command line error, 4 is returned and the +usage message is displayed. +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.I /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). +.SH SEE ALSO +.BR autofs (1), +.BR autofsd (1), +.BR PCPintro (1), +.BR pmdashping (1), +.BR pmie (1) +and +.BR RPC (3). diff --git a/man/man1/chkhelp.1 b/man/man1/chkhelp.1 new file mode 100644 index 0000000..3fc950d --- /dev/null +++ b/man/man1/chkhelp.1 @@ -0,0 +1,148 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2001 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH CHKHELP 1 "PCP" "Performance Co-Pilot" +.SH NAME +\f3chkhelp\f1 \- check performance metrics help text files +.SH SYNOPSIS +\f3$PCP_BINADM_DIR/chkhelp\f1 +[\f3\-eHiOp\f1] +[\f3\-n\f1 \f2pmnsfile\f1] +[\f3\-v\f1 \f2version\f1] +\f2helpfile\f1 +[\f2metricname\f1 ...] +.SH DESCRIPTION +.B chkhelp +checks the consistency of +Performance Co-Pilot +help text files +generated by +.BR newhelp (1) +and used by +Performance Metric Domain Agents (PMDAs). +The checking involves scanning the files, and optionally +displaying selected entries. +.PP +The files +\f2helpfile\f3.dir\f1 and +\f2helpfile\f3.pag\f1 are +created by +.BR newhelp (1), +and are assumed to already exist. +.PP +Without any options or +.I metricname +arguments, +.B chkhelp +silently verifies the structural integrity of the +help files. +.PP +If any +.I metricname +arguments are specified, then the help entries for only the corresponding +metrics will be processed. +.PP +If no +.I metricname +arguments are specified, then +at least one of the options +.B \-i +or +.B \-p +must be given. +The +.B \-i +option causes entries for all +instance domains to be processed (ignoring entries for performance +metrics). +The +.B \-p +option causes entries for all metrics to be displayed (ignoring +entries for instance domains). +.PP +When metric entries are to be processed (via either the +.I metricname +arguments or the +.B \-p +option or the +.B \-i +option), the +.B \-O +and +.B \-H +options request the display of the one-line and verbose help text respectively. +The default is +.BR \-O . +.PP +Although historically there have been multiple help text file formats, the only +format currently supported +using the +.B \-v +option is +.I version +2, and +this is the default if no +.B \-v +flag is provided. +.PP +Normally +.B chkhelp +operates on the default Performance Metrics Namespace (PMNS), however +if the +.B \-n +option is specified an alternative namespace is loaded +from the file +.IR pmnsfile . +.PP +The +.B \-e +option provides an existence check where all of the specified +metrics from the PMNS (note, not from +.IR helpfile ) +are scanned, and only the names of the metrics for which +.B no +help text exists are reported. The +.B \-e +option is mutually exclusive with the +.B \-i +and/or +.B \-p +options. +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.I /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). +.SH SEE ALSO +.BR newhelp (1), +.BR PMAPI (3), +.BR pmLookupInDomText (3), +.BR pmLookupText (3), +.BR pcp.conf (5) +and +.BR pcp.env (5). +.SH DIAGNOSTICS +There are all sorts of reasons a help database may be inconsistent, +the most likely is that a performance metric in the database is +not defined in the loaded PMNS. diff --git a/man/man1/collectl2pcp.1 b/man/man1/collectl2pcp.1 new file mode 100644 index 0000000..34eb88b --- /dev/null +++ b/man/man1/collectl2pcp.1 @@ -0,0 +1,85 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2013 Red Hat, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH COLLECTL2PCP 1 "PCP" "Performance Co-Pilot" +.SH NAME +\f3collectl2pcp\f1 \- import collectl data to a PCP archive +.SH SYNOPSIS +\f3collectl2pcp\f1 +[\f3\-F\f1] +[\f3\-v\f1] +[\f3\-?\f1] +\f2file\f1 +[\f2file\f1 ...] +\f2archive\f1 + +.SH DESCRIPTION +.B collectl2pcp +reads raw +.BR collectl (1) +data from each \f2file\f1 +and creates a new PCP archive with basename \f2archive\f1. +Each input \f2file\f1 may be gzipped (with \f3.gz\f1 suffix). +The PCP \f2archive\f1 and at least one input \f2file\fP are required arguments. +.PP +The options to +.B collectl2pcp +are as follows. +.TP +\f3\-F\f1 +Overwrite \f2archive\fP (and the index and meta files) if it already exists. +.TP +\f3\-v\f1 +Report progress and errors verbosely. +This also reports a count of unsupported metric data in the +.BR collectl (1) +input file(s), +which is normally silently skipped. +.TP +\f2file\f1 [\f2file\f1 ...] +These are the +.BR collectl (1) +input files. +If more than one is given, +they must contain data for the same host and be given in +time-stamp chronological order on the command line. +Note that when +.BR collectl (1) +is run as a service, +it normally creates files with date based names that will sort chronologically +(e.g. \f3/var/log/collectl/*.gz\f1 will be sorted correctly). +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.I /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). +.SH SEE ALSO +.BR collectl (1), +.BR pmcollectl (1), +.BR PCPIntro (1), +.BR LOGIMPORT (3), +.BR pcp.conf (5), +.BR pcp.env (5) +and +.BR pmns (5). diff --git a/man/man1/dbpmda.1 b/man/man1/dbpmda.1 new file mode 100644 index 0000000..9d31a06 --- /dev/null +++ b/man/man1/dbpmda.1 @@ -0,0 +1,495 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH DBPMDA 1 "PCP" "Performance Co-Pilot" +.SH NAME +\f3dbpmda\f1 \- debugger for Performance Co-Pilot PMDAs +.SH SYNOPSIS +\f3dbpmda\f1 +[\f3\-ei\f1] +[\f3\-n\f1 \f2pmnsfile\f1] +[\f3\-q\f1 \f2timeout\f1] +[\f3\-U\f1 \f2username\f1] +.SH DESCRIPTION +.B dbpmda +is an interactive interface to the interactions between a +Performance Metric Domain Agent +.RB ( PMDA (3)) +and the Performance Metric Collector Daemon +.RB ( pmcd (1)). +This allows PMDAs to be attached, initialized and exercised to test for +correctness. +.PP +.B dbpmda +interactively prompts the user for commands, many of which emulate the +Protocol Data Units (PDUs) that may be sent by a +.BR pmcd (1) +process. +After running +.BR dbpmda , +enter the command +.B help +to get a list of the available commands. +The example section below illustrates +a session using +.B dbpmda +to test a PMDA. +.PP +To simplify repetitive testing of a PMDA, the file +.I .dbpmdarc +in the current working directory can contain a list of commands that will be +executed by +.B dbpmda +on startup, before the user is prompted to enter further commands +interactively. While processing the +.I .dbpmdarc +file, interactive mode and command echoing are enabled and then +reset at the end of the +.I .dbpmdarc +file (see the +.I \-i +and +.I \-e +command line arguments below). +.PP +If the system supports +.BR readline (3) +then this will be used to read commands when input is from a tty +device, so history and command line editing are available. +.PP +.B dbpmda +accepts the following command line arguments: +.TP +.B \-e +Echo the input to +.BR stdout . +This is useful when the input is redirected from a file. +.TP +.B \-i +Emulate interactive behavior and prompt for new commands, even if standard +input is not a tty device. +.TP +\f3\-n\f1 \f2pmnsfile\f1 +Normally +.B dbpmda +operates on the distributed Performance Metrics Name Space (PMNS), however if +the +.B \-n +option is specified an alternative local PMNS is loaded from the file +.IR pmnsfile . +.TP +\f3\-q\f1 \f2timeout\f1 +The pmcd to agent version exchange protocol (new in PCP 2.0 - introduced to +provide backward compatibility) uses this timeout to specify how long \f3dbpmda\f1 +should wait before assuming that no version response is coming from an agent. +If this timeout is reached, the agent is assumed to be an agent which does +not understand the PCP 2.0 protocol. +The default timeout interval is five seconds, +but the +.B \-q +option allows an alternative timeout interval (which must be greater than +zero) to be specified. The unit of time is seconds. +.TP +\f3\-U\f1 \f2username\f1 +User account under which to run +.BR dbpmda . +.PP +As there are no timeout constraints on a PMDA while using +.B dbpmda +(as compared to +.BR pmcd (1)), +another debugger like +.BR gdb (1) +can be used on the PMDA process once it has been attached to +.BR dbpmda . +.SH EXAMPLE +Below is a +.B dbpmda +session using the +.I simple +PMDA. A +.B \.dbpmdarc +file is used to set the debugging flag, open the PMDA and display the +current status of the debugger: +.PP +.nf +.ft CW +.in +0.5i +$ cat .dbpmdarc +debug libpmda +open dso pmda_simple.so simple_init 253 +status +.fi +.in +.PP +When +.B dbpmda +is run, the commands in the +.B \.dbpmdarc +file are executed first: +.PP +.nf +.ft CW +.in +0.5i +$ dbpmda +\&.dbpmdarc> debug libpmda +\&.dbpmdarc> open dso pmda_simple.so simple_init 253 +[Fri Sep 19 10:19:55] dbpmda(11651) Debug: pmdaInit: PMDA simple DSO: Metric 0.0.1(1) matched to indom 253.0(0) +[Fri Sep 19 10:19:55] dbpmda(11651) Debug: pmdaInit: PMDA simple DSO: help file $PCP_PMDAS_DIR/simple/help opened +[Fri Sep 19 10:19:55] dbpmda(11651) Info: name = simple DSO +[Fri Sep 19 10:19:55] dbpmda(11651) Info: domain = 253 +[Fri Sep 19 10:19:55] dbpmda(11651) Info: num metrics = 4 +[Fri Sep 19 10:19:55] dbpmda(11651) Info: num indom = 1 +[Fri Sep 19 10:19:55] dbpmda(11651) Info: direct map = 1 +\&.dbpmdarc> status + +Namespace: (default) +PMDA: ./pmda_simple.so +Connection: dso +DSO Interface Version: 2 +PMDA PMAPI Version: 2 +pmDebug: 32768 ( libpmda ) +Timer: off +Getdesc: off + +Dump Instance Profile state=INCLUDE, 0 profiles + +\&.dbpmdarc> +.fi +.in +.PP +To examine the metric and instance descriptors, the +.B desc +and +.B instance +commands can be used. Metrics may be identified either by name, or using the +``dotted'' notation to specify the domain, cluster and item fields of a +PMID. Instance domains must be identified using a ``dotted'' notation to +specify the domain and serial fields. The syntax for most commands will be +displayed if the command is given without any arguments: +.PP +.nf +.ft CW +.in +0.5i +dbpmda> desc 253.0.0 +PMID: 253.0.0 + Data Type: 32-bit unsigned int InDom: PM_INDOM_NULL 0xffffffff + Semantics: instant Units: none +dbpmda> instance +instance indom# [ number | name | "name" ] +dbpmda> instance 253.0 +pmInDom: 253.0 +[ 0] inst: 0 name: "red" +[ 1] inst: 1 name: "green" +[ 2] inst: 2 name: "blue" +.fi +.in +.PP +To test the most important component of a PMDA, the +.BR fetch , +it is often useful to determine the time it takes the PMDA to respond. +The +.B timer +may be turned on before giving a +.BR fetch : +.PP +.nf +.ft CW +.in +0.5i +dbpmda> timer on +dbpmda> fetch simple.numfetch 253.0.1 +PMID(s): 253.0.0 253.0.1 +pmResult dump from 0x100078e0 timestamp: 0.000000 11:00:00.000 numpmid: 2 + 253.0.0 (simple.numfetch): numval: 1 valfmt: 0 vlist[]: + value 1 1.4012985e-45 0x1 + 253.0.1 (simple.color): numval: 3 valfmt: 0 vlist[]: + inst [0 or ???] value 1 1 1.4012985e-45 0x1 + inst [1 or ???] value 101 1.4153114e-43 0x65 + inst [2 or ???] value 201 2.8166099e-43 0xc9 +Timer: 0.003921 seconds +dbpmda> timer off +.fi +.in +.PP +The integer, floating point and hex translations of the values in the +.I pmResult +structure are dumped if +.B getdesc +is set to +.B off +(the default). +Setting +.B getdesc +to +.B on +would result in only integer values being dumped in the above fetch as the +descriptor describes the metrics of 32-bit unsigned integers. +.PP +The simple PMDA also supports the +.B store +operation +which can be tested with subsequent +.B fetch +commands: +.PP +.nf +.ft CW +.in +0.5i +dbpmda> store simple.numfetch "42" +PMID: 253.0.0 +Getting description... +Getting Result Structure... +253.0.0: 2 -> 42 +dbpmda> fetch simple.numfetch +PMID(s): 253.0.0 +pmResult dump from 0x100078e0 timestamp: 0.000000 11:00:00.000 numpmid: 1 + 253.0.0 (simple.numfetch): numval: 1 valfmt: 0 vlist[]: + value 43 +.fi +.in +.PP +A +.B profile +can be specified for each instance domain which includes all, some or no +instances: +.PP +.nf +.ft CW +.in +0.5i +dbpmda> help profile + +profile indom# [ all | none ] +profile indom# [ add | delete ] number + +For the instance domain specified, the profile may be changed to +include 'all' instances, no instances, add an instance or delete +an instance. + +dbpmda> profile 253.0 none +dbpmda> getdesc on +dbpmda> fetch 253.0.1 +PMID(s): 253.0.1 +pmResult dump from 0x100078e0 timestamp: 0.000000 11:00:00.000 numpmid: 1 + 253.0.1 (simple.color): No values returned! +dbpmda> profile 253.0 add 2 +dbpmda> fetch 253.0.1 +PMID(s): 253.0.1 +pmResult dump from 0x100078e0 timestamp: 0.000000 11:00:00.000 numpmid: 1 + 253.0.1 (simple.color): numval: 1 valfmt: 0 vlist[]: + value 202 +dbpmda> profile 253.0 add 0 +dbpmda> fetch 253.0.1 +PMID(s): 253.0.1 +pmResult dump from 0x100078e0 timestamp: 0.000000 11:00:00.000 numpmid: 1 + 253.0.1 (simple.color): numval: 2 valfmt: 0 vlist[]: + inst [0 or ???] value 2 + inst [2 or ???] value 203 +dbpmda> status + +PMDA = pmda_simple.so +Connection = dso +pmDebug = 32768 ( libpmda ) +Timer = off + +Dump Instance Profile state=INCLUDE, 1 profiles + Profile [0] indom=1061158913 [253.0] state=EXCLUDE 2 instances + Instances: [2] [0] +dbpmda> quit +.fi +.PP +The +.B watch +command (usage: +.B watch +.I filename +) opens an xwsh window which tails the specified log file. +This window must be closed by the user when no longer required. +.PP +The +.B wait +command is equivalent to +.B sleep (1) +and takes a single integer argument. +.PP +The introduction of dynamic subtrees in the +PMNS and PMDA_INTERFACE_4 in +.I libpcp_pmda +has led to additional commands being supported in +.B dbpmda +to exercise the associated dynamic PMNS services. The examples below are based +on the +.I sample +PMDA. +.PP +.nf +.ft CW +.in +0.5i +$ dbpmda +dbpmda> open pipe /var/lib/pcp/pmdas/sample/pmdasample \-d 29 +dbpmda> Start pmdasample PMDA: /var/lib/pcp/pmdas/sample/pmdasample \-d 29 +dbpmda> children sample.secret +Metric: sample.secret + non-leaf foo + leaf bar +dbpmda> traverse sample.secret.foo +Metric: sample.secret.foo + sample.secret.foo.bar.max.redirect + sample.secret.foo.one + sample.secret.foo.two + sample.secret.foo.bar.three + sample.secret.foo.bar.four + sample.secret.foo.bar.grunt.five + sample.secret.foo.bar.grunt.snort.six + sample.secret.foo.bar.grunt.snort.huff.puff.seven +dbpmda> pmid sample.secret.foo.bar.four +Metric: sample.secret.foo.bar.four + 29.0.1004 +dbpmda> name 29.0.1006 +PMID: 29.0.1006 + sample.secret.foo.bar.grunt.snort.six +.fi +.in +.PP +The +.B children +command returns the next name component for all the direct descendants +of a node within a dynamic subtree of the PMNS. +The related +.B traverse +command returns the full metric names for all leaf nodes in the PMNS +below the specified non-leaf node in a dynamic subtree of the PMNS. +.PP +The +.B name +and +.B pmid +commands exercise the translation of metric names to PMIDs (and vice +versa) for metrics within a dynamic subtree of the PMNS. +.PP +If the commands +.BR children , +.BR traverse , +.B pmid +or +.B name +are used with a PMDA that is +.B not +using PMDA_INTERFACE_4 or with performance metric names that +are not part of a dynamic subtree of the PMNS, then the PMDA +would be expected to return errors +(PM_ERR_NAME or PM_ERR_PMID) to reflect the fact that +the operation is in error (outside a dynamic subtree of the PMNS +it is +.BR pmcd (1) +and not the PMDA that +is responsible for implementing these functions). +.PP +Client authentication mechanisms have been incorporated into +the PMCS, providing per-user (and per-connection) information +that is available to PMDAs. +A PMDA using PMDA_INTERFACE_6 or later in +.I libpcp_pmda +is able to make use of the "attribute" method to gain visibility +into these authenticated connections, with access to information +including user and group identifiers, user name, and so on. +The need to exercise and debug this interface has led to a new +.B dbpmda +command. +The following example is based on the +.I sample +PMDA. +.PP +.nf +.ft CW +.in +0.5i +$ dbpmda +dbpmda> open pipe pmdasample \-D AUTH \-l logfile +dbpmda> Start pmdasample PMDA: pmdasample \-D AUTH \-l logfile +dbpmda> attr "username" "tanya" +Attribute: username=tanya +Success +dbpmda> attr 11 "0" +Attribute: userid=0 +Success +dbpmda> +.fi +.in +.PP +The +.B attr +command passes connection attributes (PCP_ATTR keys) and their +values into a PMDA in much the same way that PMCD would for a +client connection. +.B dbpmda +always passes a client context identifier of zero, and while no +validity checking on values is performed only recognised attributes +can be set. +.PP +In the example above the +.I AUTH +debug flag is set for the PMDA, which +uses this in its attribute callback and records each attribute and +value pair sent to it in its +.IR logfile . +.PP +Note that authentication checks have already been performed by PMCD +by the time a PMDA is presented with these attributes, so no further +verification is necessary by the PMDA. +.SH CAVEATS +A value cannot be stored into metrics of type +.B PM_TYPE_AGGREGATE +or +.BR PM_TYPE_EVENT . +.PP +.B dbpmda +uses +.BR fork (2) +and +.BR exec (2) +to attach to daemon PMDAs. +.B dbpmda +makes no attempt to detect the termination of the daemon PMDA process, so it is +possible for a PMDA to exit unexpectedly without any notification. However, +any further communication attempts with the PMDA will result in errors which +will indicate that the PMDA is no longer responding. +.SH FILES +.TP 10 +.I ./.dbpmdarc +List of commands to do on startup. +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.I /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). +.SH SEE ALSO +.BR gdb (1), +.BR pmcd (1), +.BR pmdbg (1), +.BR exec (2), +.BR fork (2), +.BR PMAPI (3), +.BR PMDA (3), +.BR pcp.conf (5) +and +.BR pcp.env (5). diff --git a/man/man1/genpmda.1 b/man/man1/genpmda.1 new file mode 100644 index 0000000..018fbae --- /dev/null +++ b/man/man1/genpmda.1 @@ -0,0 +1,139 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2005 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH GENPMDA 1 "PCP" "Performance Co-Pilot" +.SH NAME +\f3genpmda\f1 \- Performance Co-Pilot PMDA Generator +.SH SYNOPSIS +\f3genpmda\f1 [\f3\-d\f1] [\f3\-D\f1 \f2domain\f1] [\f3\-s\f1 \f2stdpmid\f1] [\f3\-t\f1 \f2topdir\f1] [\f3\-n\f1 \f2pmns\f1] [\f3\-o\f1 \f2dir\f1] [\f3\-v\f1] \f3\-i\f1 \f2IAM\f1 \f3\-c\f1 \f2config\f1 +.SH DESCRIPTION +.B Genpmda +is a rapid application development tool for creating new +Performance Metrics Domain Agents, see +.BR PMDA (3). +It provides a very easy and efficient way to extend +the Performance Co-pilot (PCP) with new performance metrics +without needing to understand the low level details of how PMDAs are +constructed. +.PP +.B Genpmda +reads a config file containing an augmented +Performance Metrics Name Space, see +.BR pmns (5), +and automatically generates virtually all of the source code +to implement a fully functional PMDA, including the Makefile, +name space, support scripts for configuring the new PMDA, +and the metrics help text. +Fairly simple PMDAs can be automatically generated from the +config file without writing any additional code. +More complicated PMDAs, e.g. containing multiple instance domains, +require only the refresh methods for the instance domains to be +written manually. +.PP +An example of the config file format accepted by +.B genpmda +is given below. +.SH OPTIONS +.TP 0 +.B "Required options:" +.TP 7 +.BI "\-c" " config" +input \f2config\f1 file, see example below +.TP 7 +.BI "\-i" " IAM" +pmda name \f2IAM\f1, should appear in \f2stdpmid\f1 or the \f3\-D\f1 option must be used to specify a \f2domain\f1. +.TP 0 +.B "Other options:" +.TP 7 +.BI "\-d" +generate an Install script for a daemon PMDA (default is DSO) +.TP 7 +.BI "\-t" " topdir" +use \f2topdir\f1 in generated GNUmakefile, default \f3../../..\f1 +.TP 7 +.BI "\-n" " pmns" +use \f2pmns\f1 as root of the namespace (default matches \f3\-i\f1 flag) +.TP 7 +.BI "\-D" " domain" +use \f2domain\f1 number in the generated \f3pmns\f1 and \f3domain.h\f1 (if \f3\-s\f1 is not given) +.TP 7 +.BI "\-s" " stdpmid" +path to \f2stdpmid\f1 (default \f3../../pmns/stdpmid\f1) +.TP 7 +.BI "\-o" " dir" +use \f2dir\f1 for generated source code, default \f3./generated\f1 +.TP 7 +.BI "\-v" +print verbose messages about what +.B genpmda +is doing. +.PP +Example: + Generate an "example" pmda using domain 99: +.br + \f3genpmda \-D 99 \-v \-i EXAMPLE \-c example.conf\f1 + +Here is \f2example.conf\f1 config file (for the required \f3\-c\f1 option): +.br +.in +0.5i +.sp +.nf +example { + metric +} + +example.metric { + ## metric string + ## pmid EXAMPLE:CLUSTER:0 + ## indom PM_INDOM_NULL + ## type PM_TYPE_STRING + ## units PMDA_PMUNITS(0,0,0,0,0,0) + ## semantics PM_SEM_DISCRETE + ## briefhelptext one line help text for example.metric.string + ## helptext long help text for example.metric.string + ## helptext This is the second line of the long help text + ## helptext and this is the third line. + ## fetch function example_string_fetch_callback + ## code atom->cp = "hello world"; + ## code return 1; + ## endmetric +} + +.fi +.sp 2 +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.I /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). +.SH SEE ALSO +.PP +.BR PMDA (3), +.BR pmns (5), +.BR pmcd (1), +.BR pcp.conf (5) +and +.BR pcp.env (5). +.SH DIAGNOSTICS +Many, but all are intended to be easily understood. diff --git a/man/man1/mkaf.1 b/man/man1/mkaf.1 new file mode 100644 index 0000000..4b6f158 --- /dev/null +++ b/man/man1/mkaf.1 @@ -0,0 +1,161 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH MKAF 1 "PCP" "Performance Co-Pilot" +.SH NAME +\f3mkaf\f1 \- create a Performance Co-Pilot archive folio +.SH SYNOPSIS +\f3$PCP_BINADM_DIR/mkaf\f1 +[\f2findopts\f1] +\f2filename\f1 ... +.SH DESCRIPTION +A collection of one or more Performance Co-Pilot (see +.BR PCPIntro (1)) +archive logs may be combined with +.B mkaf +to produce a PCP archive folio and the associated archive +folio control file. +Some PCP tools use +.B mkaf +to create archive folios, e.g. the ``record'' facility in the +.BR pmchart (1) +and +.BR pmview (1) +tools, to facilitate playback with +.BR pmafm (1). +.PP +.B mkaf +processes each +.I filename +argument, and if this is a component file from a PCP archive +that archive is added to the folio. +.PP +If +.I filename +is a directory, then this is searched recursively using +.BR find (1). +Any +.I filename +argument beginning with a ``\-'' is assumed to be a +.BR find (1) +command line option +.RI ( findopts ); +the default is +.B -follow +if no +.I findopts +are specified. +.PP +The first named +archive in the folio is assumed to be +associated with the default host for any tool that tries to +replay multiple archives from the folio. +.PP +The folio control file is written to standard output, and has the +following format. +.IP 1. 3n +The first line contains the word +.BR PCPFolio . +.IP 2. +The second line contains the tag +.B Version: +followed by the format version number (currently 1). +.IP 3. +For subsequent lines, blank lines and lines beginning with ``#'' +are ignored. +.IP 4. +The line beginning with the tag +.B Created: +documents where and when the folio was created. +.IP 5. +The line beginning with the tag +.B Creator: +identifies the tool which created the folio (and is assumed to know +how to replay the archive folio). +If present, the second argument is the name of a configuration file +that the creator tool could use to replay the archive folio, +e.g. with the +.B replay +command for +.BR pmafm (1). +In the case of +.B mkaf +(unlike +.BR pmchart (1) +or +.BR pmview (1)) +there is no knowledge of the contents of the archives, so the ``creator'' +cannot replay the archive, however +.BR pmchart (1) +is able to replay any archive, and so this tool is identified as the +.B Creator: +for archive folios created by +.BR mkaf (1). +.IP 6. +This is then followed by one or more lines beginning with the tag +.B Archive: +followed by the hostname and base name of the archive. +.PP +For example +.ti +5n +$ mkaf mydir/gonzo +.br +might produce the following folio control file. +.PP +.ft CW +.nf +PCPFolio +Version: 1 +# use pmafm(1) to process this PCP archive folio +# +Created: on gonzo at Tue Jul 2 03:35:54 EST 1996 +Creator: pmchart +# Host Basename +# +Archive: gonzo mydir/gonzo/960627 +Archive: gonzo mydir/gonzo/960628 +Archive: gonzo mydir/gonzo/960629 +Archive: gonzo mydir/gonzo/960630 +Archive: gonzo mydir/gonzo/960701 +Archive: gonzo mydir/gonzo/960701.00.10 +Archive: gonzo mydir/gonzo/960701.05.25 +Archive: gonzo mydir/gonzo/960702.00.10 +.ft +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.I /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). +.SH SEE ALSO +.BR find (1), +.BR PCPIntro (1), +.BR pmafm (1), +.BR pmchart (1), +.BR pmview (1), +.BR pcp.conf (5) +and +.BR pcp.env (5). +.SH DIAGNOSTICS +Some informational messages, warnings and pathological conditions are +reported on standard error. diff --git a/man/man1/newhelp.1 b/man/man1/newhelp.1 new file mode 100644 index 0000000..933eab6 --- /dev/null +++ b/man/man1/newhelp.1 @@ -0,0 +1,160 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.\" +.TH NEWHELP 1 "PCP" "Performance Co-Pilot" +.SH NAME +\f3newhelp\f1 \- generate a performance metrics help database +.SH SYNOPSIS +\f3$PCP_BINADM_DIR/newhelp\f1 +[\f3\-V\f1] +[\f3\-n\f1 \f2pmnsfile\f1] +[\f3\-o\f1 \f2outputfile\f1] +[\f3\-v\f1 \f2version\f1] +[\f2file\f1 ...] +.SH DESCRIPTION +.B newhelp +generates the +Performance Co-Pilot +help text files used by +Performance Metric Domain Agents (PMDAs). +.PP +Normally +.B newhelp +operates on the default Performance Metrics Namespace (PMNS), however +if the +.B \-n +option is specified an alternative namespace is loaded +from the file +.IR pmnsfile . +.PP +When there is only one input file, +the base name of the new database is derived from the name of the input +.IR file , +otherwise the +.B \-o +flag must be given to explicitly name the database. +If no input files are supplied, +.B newhelp +reads from the standard input stream, +in which case the +.B \-o +flag must be given. +.PP +If the output file name is determined to be +.BR foo , +.B newhelp +will create +.B foo.dir +and +.BR foo.pag . +.PP +Although historically there have been multiple help text file formats, the only +format currently supported +using the +.B \-v +option is +.I version +2, and +this is the default if no +.B \-v +flag is provided. +.PP +The +.B \-V +flag causes verbose messages to be printed while +.B newhelp +is parsing its input. +.PP +The first line of each entry in a help source file consists of an +\&``@'' +character beginning the line +followed by a space and then +the performance metric name and a one line description of the metric. +Following lines (up to the next line beginning with ``@'' +or end of file) may contain a verbose help description. +E.g. +.PP +.ft CW +.nf +.in +0.5i +# +# This is an example of newhelp's input syntax +# +@ kernel.all.cpu.idle CPU idle time +A cumulative count of the number of milliseconds +of CPU idle time, summed over all processors. +.in +.fi +.ft 1 +.PP +Three-part numeric metric identifiers (PMIDs) may be used in place of metric names, +e.g. \c +.ft CW +60.0.23 +.ft 1 +rather than +.ft CW +kernel.all.cpu.idle +.ft 1 +in the example above. Other than for dynamic metrics +(where the existence of a metric is known to +a PMDA, but not visible in the PMNS and hence has no name that +could be known to +.IR newhelp ) +use of this syntactic variant is not encouraged. +.PP +Lines beginning with ``#'' +are ignored, as are blank lines in the file before the first ``@''. +The verbose help text is optional. +.PP +As a special case, +a ``metric'' name of the form +.I NNN.MM +(for numeric +.I NNN +and +.IR MM ) +is interpreted as an +instance domain identification, +and the text describes the instance domain. +.SH FILES +.PD 0 +.TP 10 +.BI $PCP_VAR_DIR/pmns/ * +default PMNS specification files +.PD +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.I /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). +.SH SEE ALSO +.BR chkhelp (1), +.BR PMAPI (3), +.BR pmLookupInDomText (3), +.BR pmLookupText (3), +.BR pcp.conf (5) +and +.BR pcp.env (5). diff --git a/man/man1/pcp.1 b/man/man1/pcp.1 new file mode 100644 index 0000000..3c6d7e4 --- /dev/null +++ b/man/man1/pcp.1 @@ -0,0 +1,207 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2014 Red Hat. +.\" Copyright (c) 2000 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PCP 1 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pcp\f1 \- run a command or summarize an installation +.SH SYNOPSIS +.ft 3 +\f3pcp\f1 +[pcp options...] +pcp-\f2command\f1 +[command options...] +.br +\f3pcp\f1 +[\f3\-P\f1] +[\f3\-a\f1 \f2archive\f1] +[\f3\-h\f1 \f2host\f1] +[\f3\-n\f1 \f2pmnsfile\f1] +.ft 1 +.SH DESCRIPTION +The +.B pcp +command is used in one of two modes. +By default, it summarizes the Performance Co-Pilot (PCP) installation +on the local host. +This mode can also be used to summarize the installation from a remote +.IR host , +or a historical installation from a PCP +.IR archive . +.PP +Alternatively, a +.I command +can be passed to +.B pcp +to run, again possibly in the context of a remote +.I host +or historical +.IR archive . +.SH "COMMAND MODE" +When +.B pcp +is invoked with a command to run, it will search for the named +.IR command +in +.B $PCP_BINADM_DIR +and also +.B $HOME/.pcp/bin +(these are usually scripts, and are installed with a "pcp-" prefix). +This mode of operation allows system performance tools to be +implemented using +.BR PMAPI (3) +services, while still preserving all of their usual command line +options. +These options are thus (indirectly) augmented with the standard PCP +option set, as described in +.BR PCPIntro (1). +.PP +This provides a convenient mechanism for obtaining retrospective or +remote monitoring capabilities while preserving the behaviour of the +system tools. +.PP +For example, the +.BR pcp-free (1) +utility can be invoked as follows, for recorded data from host +.IR munch : +.PP +.nf +.ft CW +$ pcp -a $PCP_LOG_DIR/pmlogger/\fImunch\fP/20140317 \-O 11:35:50am \fBfree \-m\fP + total used free shared buffers cached +Mem: 23960 14554 9406 0 176 2137 +-/+ buffers/cache: 12240 11720 +Swap 12047 0 12047 +.ft R +.fi +.PP +A complete list of the available and installed tools is provided +along with the +.BR pcp (1) +usage message, but some examples include: +.BR pcp-free (1), +.BR pcp-uptime (1) +and +.BR pcp-numastat (1). +.SH "SUMMARY MODE" +The +summary report includes: the OS version, a summary of the hardware inventory, +the local timezone, the PCP software version, the state of the +.BR pmcd (1) +process and associated Performance Metrics Domain Agents +(PMDAs), as well as information about any PCP archive loggers (\c +.BR pmlogger (1)) +and PCP inference engines (\c +.BR pmie (1)) +that are running. +.PP +With no arguments, +.B pcp +reports on the local host, however the +following options are accepted: +.IP "\f3\-a\f1 \f2archive\f1" +Report the PCP +configuration as described in the PCP archive log +.IR archive . +.IP "\f3\-h\f1 \f2host\f1" +Report the PCP configuration on +.I host +rather than the local host. +.IP "\f3\-n\f1 \f2pmnsfile\f1" +Load an alternative Performance Metrics Name Space +.RB ( pmns (5)) +from the file +.IR pmnsfile . +.IP \f3\-P\f1 +Display +.B pmie +performance information \- counts of rules evaluating to true, false, or +indeterminate, as well as the expected rate of rule calculation, for each +.B pmie +process running on the default host. +Refer to the individual metric help text for full details on these values. +.PP +All of the displayed values are performance +.I metric +values and further information for each can be obtained using the command: +.in 1.0i +.ft CW +.nf + +$ pminfo \-dtT \f2metric\f1 + +.fi +.ft R +.in +The complete set of +.IR metric s +required by +.B pcp +to produce its output is contained in +.BR $PCP_VAR_DIR/config/pmlogconf/tools/pcp-summary . +.SH FILES +.PD 0 +.TP 10 +.B $HOME/.pcp/bin +Per-user location for +.I command +scripts. +.TP +.B $PCP_BINADM_DIR +System location for installed +.I command +scripts. +.TP +.B $PCP_VAR_DIR/config/pmlogconf/tools/pcp-summary +.BR pmlogconf (1) +configuration file for collecting all of the metrics required by +.BR pcp . +.PD +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.B /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). +.SH SEE ALSO +.BR PCPIntro (1), +.BR pcp-free (1), +.BR pcp-uptime (1), +.BR pcp-numastat (1), +.BR pmcd (1), +.BR pmie (1), +.BR pmlogconf (1), +.BR pmlogger (1), +.BR pcp.conf (5) +and +.BR pcp.env (5). +.SH DIAGNOSTICS +.B pcp +will terminate with an exit status of +.B 1 +if +.B pmcd +on the target host could not be reached or the archive could not be opened, +or +.B 2 +for any other error. diff --git a/man/man1/pcpintro.1 b/man/man1/pcpintro.1 new file mode 100644 index 0000000..c82159f --- /dev/null +++ b/man/man1/pcpintro.1 @@ -0,0 +1,1327 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2012-2014 Red Hat. +.\" Copyright (c) 2008 Aconex, Inc. All Rights Reserved. +.\" Copyright (c) 2000 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PCPINTRO 1 "PCP" "Performance Co-Pilot" +.SH NAME +\f3PCPIntro\f1 \- introduction to the Performance Co-Pilot (PCP) +.SH INTRODUCTION +.de CW +.ie t \f(CW\\$1\f1\\$2 +.el \fI\\$1\f1\\$2 +.. +The Performance Co-Pilot (PCP) is a toolkit designed for monitoring +and managing system-level performance. +These services are distributed and scalable +to accommodate the most complex system configurations and performance +problems. +.PP +PCP supports many different platforms, including (but not limited +to) Linux, MacOSX, Solaris and Windows. +From a high-level PCP can be considered to contain two classes of +software utility: +.IP "\fIPCP Collectors\fR" 8 +These are the parts of PCP that collect and extract +performance data from various sources, e.g. the operating system kernel. +.IP "\fIPCP Monitors\fR" 8 +These are the parts of PCP that display data collected from +hosts (or archives) that have the +.I "PCP Collector" +installed. +Many monitor tools are available as part of the core PCP release, +while other (typically graphical) monitoring tools are available +separately in the PCP GUI package. +.PP +This manual entry describes the high-level features and +options common to most PCP utilities available on all platforms. +.SH OVERVIEW +The PCP architecture is distributed in the +sense that any PCP tool may be executing remotely. On +the host (or hosts) being monitored, each domain of performance +metrics, whether the kernel, a service layer, a database management system, a web server, an application, etc. +requires a Performance Metrics Domain Agent (PMDA) +which is responsible for collecting performance +measurements from that domain. +All PMDAs +are controlled by the Performance Metrics Collector Daemon +.RB ( pmcd (1)) +on the same host. +.PP +Client applications (the monitoring tools) connect to +.BR pmcd (1), +which +acts as a router for requests, by +forwarding requests to the appropriate +PMDA and returning the responses to the clients. +Clients may also access performance data from a PCP archive +(created using +.BR pmlogger (1)) +for retrospective analysis. +.SS Security philosophy +PCP redistributes a wealth of performance information within +a host and across its networks. The following security +philosophy underlies the setting of several +.I defaults +that control how much information is sent and received. +.PP +By default, the information exposed by PMCD about a host is +approximately of the same level of confidentiality as available +to a completely unprivileged user on that host. So, performance +data that is available to be +.I read +completely freely on a machine may be made available by PMCD to +the network. +.PP +However, the host running PMCD and its network is +.I not +assumed to run only friendly applications. Therefore, +.I write +type operations, including from the local host, are not +permitted by default. +.PP +These defaults may be overridden (expanded or reduced) in several +ways, including by specifying network ACLs in +.BR pmcd.conf , +activating non-default PMDAs, or by using PMCD connections +that pass user credentials. For example, some PMDAs automatically +provide greater information for particular credentialed users or groups. +.PP +.SS Applications +The following performance monitoring applications are primarily console +based, typically run directly from the command line, and are just a +small subset of the tools available as part of the base PCP package. +.PP +Each tool or command is documented completely in its own reference page. +.TP +.B pmstat +Outputs an ASCII high-level summary of system performance. +.TP +.B pmie +An inference engine that can evaluate predicate-action rules to perform +alarms and automate system management tasks. +.TP +.B pminfo +Interrogate specific performance metrics and the metadata that +describes them. +.TP +.B pmlogger +Generates PCP +archives of performance metrics suitable for replay by most +PCP tools. +.TP +.B pmval +Simple periodic reporting for some or all instances of a performance +metric, with optional VCR time control. +.PP +If the PCP GUI package is installed then +the following additional tools are available. +.TP +.B pmchart +Displays trends over time of arbitrarily selected performance metrics from +one or more hosts. +.TP +.B pmtime +Time control utility for coordinating the time between multiple tools +(including pmchart and pmval). +.TP +.B pmdumptext +Produce ASCII reports for arbitrary combinations of performance +metrics. +.SH COMMON COMMAND LINE ARGUMENTS +There is a set of common command line arguments that are used consistently +by most PCP tools. +.TP +.BI "\-a " archive +Performance metric information is retrospectively retrieved +from the Performance Co-Pilot (PCP) +.IR archive , +previously generated by +.BR pmlogger (1). See +.BR pcp-archive (5) for format documentation. +The +.B \-a +and +.B \-h +options are mutually exclusive. +.RS +.PP +.I archive +is either the base name common to all of the physical files created +by an instance of +.BR pmlogger (1), +or any one of the physical files, e.g. +.I myarchive +(base name) or +.IB myarchive .meta +(the metadata file) or +.IB myarchive .index +(the temporal index) or +.IB myarchive .0 +(the first data volume of +.IR archive ) +or +.IB myarchive .0.bz2 +or +.IB myarchive .0.bz +(the first data volume compressed with +.BR bzip2 (1)) +or +.IB myarchive .0.gz +or +.IB myarchive .0.Z +or +.IB myarchive .0.z +(the first data volume compressed with +.BR gzip (1)), +.IB myarchive .1 +or +.IB myarchive .3.bz2 +or +.IB myarchive .42.gz +etc. +.RE +.TP +.BI "\-a " archive\f1[ , archive , \f1...] +An alternate form of +.B \-a +for applications that are able to handle multiple +archives. +.TP +.BI "\-h " hostname +Unless directed to another host by the +.B \-h +option, +or to an archive by the +.B \-a +option, +the source of performance metrics will be +the Performance Metrics Collector Daemon (PMCD) +on the local host. +Refer to the +.B "PMCD HOST SPECIFICATION" +section later for further details on the many +options available when forming the +.I hostname +specification, as well as a detailed description of +the default local host connection. +The +.B \-a +and +.B \-h +options are mutually exclusive. +.TP +.BI "\-s " samples +The argument +.I samples +defines the number of samples to be retrieved and reported. +If +.I samples +is 0 or +.B \-s +is not specified, the application +will sample and report continuously (in real time mode) or until the end +of the PCP archive (in archive mode). +.TP +.B \-z +Change the reporting timezone to the local timezone at the +host that is the source of the performance metrics, as identified via +either the +.B \-h +or +.B \-a +options. +.TP +.BI "\-Z " timezone +By default, applications +report the time of day according to the local timezone on the +system where +the application is executed. +The +.B \-Z +option changes the timezone to +.I timezone +in the format of the environment variable +.B TZ +as described in +.BR environ (5). +.SH INTERVAL SPECIFICATION AND ALIGNMENT +Most PCP tools operate with periodic sampling or +reporting, and the +.B \-t +and +.B \-A +options may be used to control the duration of the sample interval +and the alignment of the sample times. +.TP +.BI "\-t " interval +.RS +Set the update or reporting interval. +.PP +The +.I interval +argument +is specified as a sequence of one or more elements of the form +.nf +.in +1.0i +\f2number\f1[\f2units\f1] +.in +.fi +where \f2number\f1 is an integer or floating point constant (parsed using +.BR strtod (3)) +and the optional \f2units\f1 is one of: +.BR seconds , +.BR second , +.BR secs , +.BR sec , +.BR s , +.BR minutes , +.BR minute , +.BR mins , +.BR min , +.BR m , +.BR hours , +.BR hour , +.BR h , +.BR days , +.B day +and +.BR d . +If the +.I unit +is empty, +.B second +is assumed. +.PP +In addition, the upper case (or mixed case) version of any of the +above is also acceptable. +.PP +Spaces anywhere in the +.I interval +are ignored, so +.BR "4 days 6 hours 30 minutes" , +.BR "4day6hour30min" , +.B "4d6h30m" +and +.B "4d6.5h" +are all equivalent. +.PP +Multiple specifications are additive, e.g. ``\fB1hour 15mins 30secs\fR'' +is interpreted as 3600+900+30 seconds. +.RE +.TP +.BI "\-A " align +.RS +By default samples are not necessarily aligned on +any natural unit of time. The +.B \-A +option may be used to force the initial sample to be aligned on the +boundary of a natural time unit. +For example +.BR "\-A 1sec" , +.B "\-A 30min" +and +.B "-A 1hour" +specify alignment on whole seconds, half and whole hours respectively. +.PP +The +.I align +argument follows the syntax for an +.I interval +argument described above for the +.B \-t +option. +.PP +Note that alignment occurs by advancing the time as required, and that +.B \-A +acts as a modifier to advance both the start of the time window +(see the next section) +and the origin time (if the +.B \-O +option is specified). +.RE +.SH TIME WINDOW SPECIFICATION +Many PCP tools are designed to operate in some time window of interest, +e.g. to define a termination time for real-time monitoring or to +define a start and end time within a PCP archive log. +.PP +In the absence of the +.B \-O +and +.B \-A +options to specify an initial sample time origin +and time alignment (see above), the PCP application +will retrieve the first sample at the start of the time window. +.PP +The following options may be used to specify a time window of interest. +.TP +.BI "\-S " starttime +.RS +By default the time window commences immediately in real-time mode, +or coincides with time at the start of the PCP archive log +in archive mode. +The +.B \-S +option may be used to specify a later time +for the start of the time window. +.P +The +.I starttime +parameter may be given in one of +three forms (\c +.I interval +is the same as for the +.B \-t +option as described above, +.I datetime +is described below): +.TP +\f2interval\f1 +To specify an offset from the current time (in real-time mode) or +the beginning of a PCP archive (in archive mode) simply specify the +interval of time as the argument. For example +.B "\-S 30min" +will set the start of the time window to be exactly 30 minutes from now in +real-time mode, or +exactly 30 minutes from +the start of a PCP archive. +.TP +\-\f2interval\f1 +To specify an offset from the end of a PCP archive log, prefix the +\f2interval\f1 argument with a minus sign. In this case, the +start of the time window precedes +the time at the end of archive by the given interval. +For example +.B "\-S \-1hour" +will set the start of the time window to be exactly one hour before the +time of the last sample in a PCP archive log. +.TP +@\f2datetime\f1 +To specify the calendar date and time (local time in the reporting timezone) +for the start of the time window, use the datetime +syntax preceded by an at sign. Refer to the datetime description below +for detailed information. +.RE +.TP +.BI "\-T " endtime +.RS +By default the end of the time window is unbounded +(in real-time mode) or aligned with the time at the end of a PCP archive +log (in archive mode). +The +.B \-T +option may be used to specify an earlier time for +the end of the time window. +.PP +The +.I endtime +parameter may be given in one of +three forms (\c +.I interval +is the same as for the +.B \-t +option as described above, +.I datetime +is described below): +.TP +\f2interval\f1 +To specify an offset from the start of the time window +simply use the interval of time as the argument. For example +.B "\-T 2h30m" +will set the end of the time window to be 2 hours and 30 minutes after +the start of the time window. +.TP +\-\f2interval\f1 +To specify an offset back from the time at the end of a PCP archive log, +prefix the \f2interval\f1 argument with a minus sign. For example +.B "\-T \-90m" +will set the end of the time window to be 90 minutes before the time of +the last sample in a PCP archive log. +.TP +@\f2datetime\f1 +To specify the calendar date and time (local time in the reporting timezone) +for the end of the time window, use the datetime +syntax preceded by an at sign. Refer to the datetime description below +for detailed information. +.RE +.TP +.BI "\-O " origin +.RS +By default samples are fetched from the start of the +time window (see description of +.B \-S +option) to the end of the time window (see description of +.B \-T +option). +The +.B \-O +option allows the specification of an origin within the time window +to be used as the initial sample time. This +is useful for interactive use of a PCP tool with the +.BR pmtime (1) +VCR replay facility. +.PP +The \f2origin\f1 argument accepted by +.B \-O +conforms to the same syntax and semantics as the +.I starttime +argument for the +.B \-T +option. +.PP +For example +.B "\-O -0" +specifies that the initial position should be at the end of the +time window; this is most useful when wishing to replay ``backwards'' +within the time window. +.RE +.PP +The \f2datetime\f1 argument for the +.BR \-O , +.B \-S +and +.B \-T +options consists of: +.br +.ti +1i +.B "date time zone day relative" +.br +A date can be one of: +YY-MM-DD, MM/DD/YY, DD Month YYYY, or Month DD YYYY. +A time can be one of: HH:MM:SS, HH:MM. HH:MM can use either the +12 hour (via an am or pm suffix) or 24 hour convention. +A day of the +week can be a spelled out day of the week, optionally preceded by an +ordinal number such as second tuesday. A zone is a time zone value as +specified by the +.B tzselect(1) +command. A relative time can be a time +unit that is: preceded by a cardinal number such as 1 year or 2 months, +preceded by one of the time words this or last, or succeeded by the time word ago. +A relative time can also be one of the time words: yesterday, today, tomorrow, now. +Examples of datetime strings are: +.BR "1996-03-04 13:07:47 EST Mon" , +.BR "1996-03-05 14:07:47 EST -1hour" , +.BR "Mon Mar 4 13:07:47 1996" , +.BR "Mar 4 1996" , +.BR "Mar 4" , +.BR "Mar" , +.B "13:07:50" +or +.BR "13:08" . +.PP +For any missing low order fields, the default value of +0 is assumed for hours, minutes and seconds, 1 for day of the month and Jan for months. +Hence, the following are equivalent: +.B "\-S '@ Mar 1996'" +and +.BR "\-S '@ Mar 1 00:00:00 1996'" . +.PP +If any high order fields are missing, they are filled in by +starting with the +year, month and day from the current time (real-time mode) or +the time at the beginning of the PCP archive log (archive mode) +and advancing the +time until it matches the fields that are specified. +So, for example if the time window starts by default at +``Mon Mar 4 13:07:47 1996'', +then +.B "\-S @13:10" +corresponds to 13:10:00 on Mon Mar 4, 1996, +while +.B "\-S @10:00" +corresponds to 10:00:00 on Tue Mar 5, 1996 (note this is the +following day). +.PP +For greater precision than afforded by +.BR datetime (3), +the seconds component may be a floating point number. +.SH "PERFORMANCE METRICS \- NAMES AND IDENTIFIERS" +The number of performance metric names supported by PCP on most +platforms ranges from many hundreds to several thousand. +The PCP libraries and applications use an internal +identification scheme that unambiguously associates a single +integer with each known performance metric. +This integer is known as the Performance Metric Identifier, or PMID. +Although not a requirement, +PMIDs tend to have global consistency across +all systems, so a particular performance metric usually has the same +PMID. +.PP +For all users and most applications, direct use of the PMIDs would be inappropriate +(e.g. this would limit the range of accessible metrics, make the code +hard to maintain, force the user interface to be particularly baroque, +etc.). +Hence a Performance Metrics Name Space (PMNS) +is used to provide external names and +a hierarchic classification for performance metrics. +A PMNS is +represented as a tree, with each node having a label, a pointer to +either a PMID (for leaf nodes) or a set of descendent +nodes in the PMNS (for non-leaf nodes). +.PP +A node label must begin with +an alphabetic character, followed by zero or more characters drawn +from the alphabetics, the digits and character \`_\' (underscore). +For alphabetic characters in a node label, upper and +lower case are distinguished. +.PP +By convention, the name of a performance metric is constructed by +concatenation of the node labels on a path through the PMNS from the +root node to a leaf node, with a ``.'' as a separator. +The root node in +the PMNS is unlabeled, so all names begin with the label associated +with one of the descendent nodes below the root node of the PMNS, e.g. \c +.CW "kernel.percpu.syscall". +Typically (although this is not a requirement) +there would be at most one name for each PMID in a PMNS. +For example +.CW kernel.all.cpu.idle +and +.CW disk.dev.read +are the unique names for two distinct performance +metrics, each with a unique PMID. +.PP +Groups of related PMIDs may be named +by naming a non-leaf node in the PMNS tree, e.g. \c +.CW disk . +.PP +The default local PMNS used by +.B pmcd +is located at +.B $PCP_VAR_DIR/pmns/root +however the environment +variable +.B PMNS_DEFAULT +may be set to the full pathname of a different PMNS which will +then be used as the default local PMNS. +.PP +Most applications do not use the local PMNS directly, +but rather import parts of the PMNS as required from the +same place that performance metrics are fetched, i.e. from +.BR pmcd (1) +for live monitoring or from a PCP archive for retrospective +monitoring. +.PP +To explore the PMNS +use +.BR pminfo (1), +or if the PCP GUI package is installed the New Chart and Metric Search +windows within +.BR pmchart (1). +.SH PERFORMANCE METRIC SPECIFICATIONS +In configuration files and (to a lesser extent) command line options, +metric specifications adhere to the following syntax rules. +.PP +If the source of performance metrics is real-time from +.BR pmcd (1) +then the accepted +syntax is +.br +.ti +1i +\fIhost\fB:\fImetric\fB[\fIinstance1\fB,\fIinstance2\fB,\fR...\fB]\fR +.PP +If the source of performance metrics is a PCP archive log then the +accepted syntax +is +.br +.ti +1i +\fIarchive\fB/\fImetric\fB[\fIinstance1\fB,\fIinstance2\fB,\fR...\fB]\fR +.PP +The +.IB host :\fR, +.IB archive / +and +\fB[\fIinstance1\fB,\fIinstance2\fB,\fR...\fB]\fR +components are all optional. +.PP +The +.B , +delimiter in the list of instance names +may be replaced by white space. +.PP +Special characters in +.I instance +names may be escaped by surrounding the name in double quotes or preceding +the character with a backslash. +.PP +White space is ignored everywhere except within a quoted +.I instance +name. +.PP +An empty +.I instance +is silently ignored, and in particular +``\fB[]\fR'' is the same as no +.IR instance , +while ``\fB[one,,,two]\fR'' is parsed as specifying just +the two instances ``\fBone\fP'' and ``\fBtwo\fP''. +.PP +As a special case, if the +.B host +is the single character ``@'' then this refers to a +.B PM_CONTEXT_LOCAL +source, see +.BR pmNewContext (3). +.SH SECURE PMCD CONNECTIONS +Since PCP version 3.6.11, a monitor can explicitly request +a secure connection to a collector host running +.BR pmcd (1) +or +.BR pmproxy (1) +using the PM_CTXFLAG_SECURE context flag. +If the PCP Collector host supports this feature - refer to the +pmcd.feature.secure metric for confirmation of this - a TLS/SSL +(Transport Layer Security or Secure Sockets Layer) connection +can be established which uses public key cryptography and related +techniques. +These features aim to prevent eavesdropping and data tampering +from a malicious third party, as well as providing server-side +authentication (confident identification of a server by a client) +which can be used to guard against man-in-the-middle attacks. +.PP +A secure +.B pmcd +connection requires use of certificate-based authentication. +The security features offered by +.B pmcd +and +.B pmproxy +are implemented using the Network Security Services (NSS) APIs and +utilities. +The NSS +.BR certutil +tool can be used to create certificates suitable for establishing +trust between PCP monitor and collector hosts. +.PP +A complete description is beyond the scope of this document, refer +to the +.BR "PCP ENVIRONMENT" , +.B "FILES" +and +.B "SEE ALSO" +sections for detailed information. +This includes links to tutorials on the steps involved in setting up the +available security features. +.SH PMCD HOST SPECIFICATION +In the absence of an explicit host name specification, most tools +will default to the local host in live update mode. +In PCP releases since 3.8.4 onward, this results in an efficient +local protocol being selected \- typically a Unix domain socket. +If this option is used (which can also be explicitly requested +via the +.I unix: +host specification described below), it is important to note that all +connections will be automatically authenticated. In other words, the +credentials of the user invoking a client tool will automatically be +made available to +.BR pmcd (1) +and all of its PMDAs, on the users behalf, such that results can be +customized to the privilege levels of individual users. +.PP +Names of remote hosts running the +.BR pmcd (1) +daemon can of course also be provided to request a remote host be used. +The most basic form of +.B pmcd +host specification is a simple host name, possibly including the +domain name if necessary. +However, this can be extended in a number of ways to further refine +attributes of the connection made to +.BR pmcd . +.PP +The +.B pmcd +port number and also optional +.BR pmproxy (1) +hostname and its port number, can be given as part of the host +specification, since PCP version 3.0. +These supersede (and override) the old-style PMCD_PORT, PMPROXY_HOST +and PMPROXY_PORT environment variables. +.PP +The following are valid hostname specifications that specify connections to +.B pmcd +on host +.I nas1.servers.com +with/without a list of ports and with/without a +.BR pmproxy (1) +connection through a firewall. +.PP +.in +0.5i +.nf +.ft CW +$ pcp \-h nas1.servers.com:44321,4321@firewall.servers.com:44322 +$ pcp \-h nas1.servers.com:44321@firewall.servers.com:44322 +$ pcp \-h nas1.servers.com:44321@firewall.servers.com +$ pcp \-h nas1.servers.com@firewall.servers.com +$ pcp \-h nas1.servers.com:44321 +.ft R +.fi +.in +.PP +In addition, security attributes and credentials can also be specified. +These include username, an optional password (can be given interactively +and may depend on the authentication mechanism employed), whether to use +secure (encrypted) or native (naked) protocol, and so on. The previous +examples all default to native protocol, and use no authentication. +This can be altered, as in the following examples. +.PP +.in +0.5i +.nf +.ft CW +$ pcp \-h pcps://nas1.servers.com:44321?username=tanya&method=gssapi +$ pcp \-h pcps://nas2.servers.com@firewalls.r.us?method=plain +$ pcp \-h pcp://nas3.servers.com +$ pcp \-h unix: +$ pcp \-h local: +.ft R +.fi +.in +.PP +The choice of authentication method, and other resulting parameters like +username, optionally password, etc, depends on the SASL2 configuration +used by each (remote) +.BR pmcd . +Tutorials are available specifying various aspects of configuring the +authentication module(s) used, these fine details are outside the scope +of this document. +.PP +The final +.I local: +example above is now the default for most tools. +This connection is an automatically authenticated local host connection +on all platforms that support Unix domain sockets. No password is required +and authentication is automatic. This is also the most efficient (lowest +overhead) communication channel available. +.PP +The difference between +.I unix: +and +.I local: +is that the former is a strict Unix domain socket specification (connection +fails if it cannot connect that way), +whereas the latter has a more forgiving fallback to using +.I localhost +(i.e. a regular Inet socket connection is used when Unix domain socket +connections are unavailable). +.SH ENVIRONMENT +In addition to the PCP run-time environment and configuration variables +described in the +.B "PCP ENVIRONMENT" +section below, +the following environment variables apply to all installations. +.TP +.B PCP_CONSOLE +When set, this changes the default console from +.I /dev/tty +(on Unix) +or +.I CON: +(on Windows) +to be the specified console. +The special value of +.I none +can be used to indicate no console is available for use. +This is used in places where console-based tools need to interact +with the user, and in particular is used when authentication is +being performed. +.TP +.B PCP_DERIVED_CONFIG +When set, this variable defines the path to a file that contains +definitions of derived metrics as per the syntax described in +.BR pmLoadDerivedConfig (3). +Derived metrics may be used to extend the available metrics with +new (derived) metrics using simple arithmetic expressions. +.RS +.PP +If +.B PCP_DERIVED_CONFIG +is set, the derived metric definitions are processed automatically +as each new source of performance metrics is established (i.e. each +time a +.BR pmNewContext (3) +is called) or when requests are made against the PMNS. +.RE +.TP +.B PCP_SECURE_SOCKETS +When set, this variable forces any monitor tool connections to be +established using the certificate-based secure sockets feature. +If the connections cannot be established securely, they will fail. +.TP +.B PCP_SECURE_DB_METHOD +With secure socket connections, the certificate and key database is +stored using the +.B sql: +method by default. Use +.B PCP_SECURE_DB_METHOD +to override the default, most usually setting the value to the empty +string (for the older database methods). +.TP +.B PCP_STDERR +Many PCP tools support the environment variable +.BR PCP_STDERR , +which can be used to +control where error messages are sent. +When unset, the default behavior is that +``usage'' messages and option parsing errors are +reported on standard error, other messages after +initial startup are sent to the default destination for the tool, +i.e. standard error for ASCII tools, or a dialog for GUI tools. +.RS +.PP +If +.B PCP_STDERR +is set to the literal value +.B DISPLAY +then all messages will be displayed in a dialog. +This is used for any tools launched from the a Desktop environment. +.PP +If +.B PCP_STDERR +is set to any other value, the value is assumed to +be a filename, and all messages will be written there. +.RE +.TP +.B PMCD_CONNECT_TIMEOUT +When attempting to connect to a remote +.BR pmcd (1) +on a machine that is booting, +the connection attempt +could potentially block for a long time until the remote machine +finishes its initialization. +Most PCP applications and some of the PCP library routines +will 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 +.B PMCD_CONNECT_TIMEOUT +in the environment to a real number of seconds for the +desired timeout. +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. +.TP +.B PMCD_RECONNECT_TIMEOUT +When a monitor or client application loses a connection to a +.BR pmcd (1), +the connection may be re-established by calling +a service routine in the PCP library. +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 will be repeated for any further +attempts after the fifth). +Setting the environment variable +.B PMCD_RECONNECT_TIMEOUT +to a comma separated list of positive integers will re-define +the back-off delays, e.g. setting +.B PMCD_RECONNECT_TIMEOUT +to ``1,2'' will back-off for 1 second, then attempt another +connection request every 2 seconds thereafter. +.TP +.B PMCD_REQUEST_TIMEOUT +For monitor or client applications connected to +.BR pmcd (1), +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 +.B pmcd +crashes, or the network connection is lost. By setting the environment +variable +.B PMCD_REQUEST_TIMEOUT +to a number of seconds, requests to +.B pmcd +will timeout after this number of seconds. The default behavior is +to be willing to wait 10 seconds for a response from every +.B pmcd +for all applications. +.TP +.B PMCD_WAIT_TIMEOUT +.br +When +.BR pmcd (1) +is started from +.B $PCP_RC_DIR/pcp +then the primary instance of +.BR pmlogger (1) +will be started if the configuration flag +.B pmlogger +is +.BR chkconfig (8) +enabled and +.B pmcd +is running and accepting connections. +.RS +.PP +The check on +.BR pmcd 's +readiness will wait up to +.B PMCD_WAIT_TIMEOUT +seconds. +If +.B pmcd +has a long startup time (such as on a very large +system), then +.B PMCD_WAIT_TIMEOUT +can be set to provide a maximum wait longer than the default 60 seconds. +.RE +.TP +.B PMNS_DEFAULT +If set, then interpreted as the +full pathname to be used as the default local PMNS for +.BR pmLoadNameSpace (3). +Otherwise, the default local PMNS is located at +.B $PCP_VAR_DIR/pcp/pmns/root +for base PCP installations. +.TP +.B PCP_COUNTER_WRAP +Many of the performance metrics exported from PCP agents have the +semantics of +.I counter +meaning they are expected to be monotonically increasing. +Under some circumstances, one value of these metrics may smaller +than the previously fetched value. +This can happen when a counter of finite precision overflows, or +when the PCP agent has been reset or restarted, or when the +PCP agent is exporting values from some +underlying instrumentation that is subject to some asynchronous +discontinuity. + +The environment variable +.B PCP_COUNTER_WRAP +may be set to indicate 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. +This ``wrapping'' behavior was the default in earlier PCP versions, but +by default has been disabled in PCP release from version 1.3 on. +.TP +.B PMDA_PATH +The +.B PMDA_PATH +environment variable +may be used to modify the search path used by +.BR pmcd (1) +and +.BR pmNewContext (3) +(for +.B PM_CONTEXT_LOCAL +contexts) when searching for a daemon or DSO PMDA. +The syntax follows that for +.B PATH +in +.BR sh (1), +i.e. a colon separated list of directories, +and the default search path is ``/var/pcp/lib:/usr/pcp/lib'', +(or ``/var/lib/pcp/lib'' on Linux, depending on the value +of the $PCP_VAR_DIR environment variable). +.TP +.B PMCD_PORT +The TPC/IP port(s) used by +.BR pmcd (1) +to create the socket for incoming connections and requests, was +historically 4321 and more recently the officially registered port +44321; in the current release, +.B both +port numbers are used by default as a transitional arrangement. +This may be over-ridden by setting +.B PMCD_PORT +to a different port number, or a comma-separated list of port numbers. +If a non-default port is used when +.B pmcd +is started, then +every monitoring application connecting to that +.B pmcd +must also have +.B PMCD_PORT +set in their environment before attempting a connection. +.PP +The following environment variables are relevant to installations +in which +.BR pmlogger (1), +the PCP archive logger, is used. +.TP +.B PMLOGGER_PORT +The environment variable +.B PMLOGGER_PORT +may be used to change the base TCP/IP port number used by +.BR pmlogger (1) +to create the socket to which +.BR pmlc (1) +instances will try and connect. +The default base port number is 4330. +When used, +.B PMLOGGER_PORT +should be set in the environment before +.B pmlogger +is executed. +.TP +.B PMLOGGER_REQUEST_TIMEOUT +When +.BR pmlc (1) +connects to +.BR pmlogger (1), +there is a remote possibility of +.BR pmlc +\&"hanging" on a request +for information as a consequence of a failure of the network or +.BR pmlogger . +By setting the environment +variable +.B PMLOGGER_REQUEST_TIMEOUT +to a number of seconds, requests to +.B pmlogger +will timeout after this number of seconds. The default behavior is +to be willing to wait forever for a response from each request to a +.BR pmlogger . +When used, +.B PMLOGGER_REQUEST_TIMEOUT +should be set in the environment before +.B pmlc +is executed. +.PP +If you have the PCP product installed, then the following +environment variables are relevant to the Performance Metrics +Domain Agents (PMDAs). +.TP +.B PMDA_LOCAL_PROC +Use this variable has been deprecated and it is now ignored. +If the ``proc'' PMDA is configured as a DSO for use with +.BR pmcd (1) +on the local host then all of the ``proc'' metrics will be +available to applications using a +.B PM_CONTEXT_LOCAL +context. +.RS +.PP +The previous behaviour was that +if this variable was set, then a context established with the +.I type +of +.B PM_CONTEXT_LOCAL +will have access to the ``proc'' PMDA to retrieve performance metrics +about individual processes. +.RE +.TP +.B PMDA_LOCAL_SAMPLE +Use this variable has been deprecated and it is now ignored. +If the ``sample'' PMDA is configured as a DSO for use with +.BR pmcd (1) +on the local host then all of the ``sample'' metrics will be +available to applications using a +.B PM_CONTEXT_LOCAL +context. +.RS +.PP +The previous behaviour was that +if this variable was set, then a context established with the +.I type +of +.B PM_CONTEXT_LOCAL +will have access to the ``sample'' PMDA if this optional PMDA has +been installed locally. +.RE +.TP +.B PMIECONF_PATH +If set, +.BR pmieconf (1) +will form its +.BR pmieconf (5) +specification (set of parameterized +.BR pmie (1) +rules) using all valid +.B pmieconf +files found below each subdirectory in this +colon-separated list of subdirectories. If not set, the default is +.BR $PCP_VAR_DIR/config/pmieconf . +.SH FILES +.PD 0 +.TP 10 +.B /etc/pcp.conf +Configuration file for the PCP runtime environment, +see +.BR pcp.conf (5). +.TP +.B /etc/pki/nssdb +Optionally contains a Network Security Services database with a +"PCP Collector" certificate providing trusted identification for +the collector host. +.TP +.B $HOME/.pcp +User-specific directories containing configuration files for +customisation of the various monitor tools, such as +.BR pmchart (1). +.TP +.B $HOME/.pki/nssdb +A shared Network Security Services (NSS) database directory +containing per-user certificates identifying known valid remote +.B pmcd +collector hosts. +The NSS +.B certutil +tool is one of several that can be used to maintain this database. +.TP +.B $PCP_RC_DIR/pcp +Script for starting and stopping +.BR pmcd (1). +.TP +.B $PCP_PMCDCONF_PATH +Control file for +.BR pmcd (1). +.TP +.B $PCP_PMCDOPTIONS_PATH +Command line options passed to +.BR pmcd (1) +when it is started from +.BR $PCP_RC_DIR/pcp . +All the command line option lines should start with a hyphen as +the first character. +This file can also contain environment variable settings of +the form "VARIABLE=value". +.TP +.B $PCP_BINADM_DIR +Location of PCP utilities for collecting and maintaining PCP archives, PMDA +help text, PMNS files etc. +.TP +.B $PCP_PMDAS_DIR +Parent directory of the installation directory for Dynamic Shared Object (DSO) PMDAs. +.TP +.B $PCP_RUN_DIR/pmcd.pid +If pmcd is running, this file contains an ascii decimal representation of its +process ID. +.TP +.B $PCP_LOG_DIR/pmcd +Default location of log files for +.BR pmcd (1), +current directory for running PMDAs. +Archives generated by +.BR pmlogger (1) +are generally below +.BR $PCP_LOG_DIR/pmlogger . +.TP +.B $PCP_LOG_DIR/pmcd/pmcd.log +Diagnostic and status log for the current running +.BR pmcd (1) +process. +The first place to look when there are problems associated +with +.BR pmcd . +.TP +.B $PCP_LOG_DIR/pmcd/pmcd.log.prev +Diagnostic and status log for the previous +.BR pmcd (1) +instance. +.TP +.B $PCP_LOG_DIR/NOTICES +Log of +.BR pmcd (1) +and +PMDA starts, stops, additions and removals. +.TP +.B $PCP_VAR_DIR/config +Contains directories of configuration files for several PCP tools. +.TP +.B $PCP_SYSCONF_DIR/pmcd/rc.local +Local script for controlling PCP boot, shutdown and restart actions. +.TP +.B $PCP_VAR_DIR/pmns +Directory containing the set of PMNS files for all installed PMDAs. +.TP +.B $PCP_VAR_DIR/pmns/root +The ASCII +.BR pmns (5) +exported by +.BR pmcd (1) +by default. This PMNS is be the super set of all other PMNS files +installed in +.BR $PCP_VAR_DIR/pmns . +.PP +In addition, if the PCP product is installed the following +files and directories are relevant. +.TP +.B $PCP_LOG_DIR/NOTICES +In addition to the +.BR pmcd (1) +and PMDA activity, may be used to log alarms and notices from +.BR pmie (1) +via +.BR pmpost (1). +.TP +.B $PCP_PMLOGGERCONTROL_PATH +Control file for +.BR pmlogger (1) +instances launched from +.B $PCP_RC_DIR/pcp +and/or managed by +.BR pmlogger_check (1) +and +.BR pmlogger_daily (1) +as part of a production PCP archive collection setup. +.PD +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.B /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). +.SH SEE ALSO +.BR pmcd (1), +.BR pmie (1), +.BR pmie_daily (1), +.BR pminfo (1), +.BR pmlc (1), +.BR pmlogger (1), +.BR pmlogger_daily (1), +.BR pmstat (1), +.BR pmval (1), +.BR pcp (1), +.BR pcp.conf (5), +.BR pcp.env (5), +.BR pmns (5) +and +.BR chkconfig (8). +.PP +If the PCP GUI package is installed, then the +following entries are also relevant: +.br +.BR pmchart (1), +.BR pmtime (1), +and +.BR pmdumptext (1). +.PP +If the secure sockets extensions have been enabled, then the +following references are also relevant: +.br +.I "http://www.performancecopilot.org/pcp-gui.git/man/html/index.html" +.br +.I "http://www.mozilla.org/projects/security/pki/nss/#documentation" +.br +.I "http://www.mozilla.org/projects/security/pki/nss/tools/certutil.html" +.PP +Also refer to the books +.I "Performance Co-Pilot User's and Administrator's Guide" +and +.IR "Performance Co-Pilot Programmer's Guide" +which can be found at http://www.performancecopilot.org/ diff --git a/man/man1/pmafm.1 b/man/man1/pmafm.1 new file mode 100644 index 0000000..6e807f0 --- /dev/null +++ b/man/man1/pmafm.1 @@ -0,0 +1,222 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMAFM 1 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmafm\f1 \- Performance Co-Pilot archive folio manager +.SH SYNOPSIS +\f3pmafm\f1 \f2folioname\f1 +[\f2command\f1 [\f2arg\f1 ...]] +.SH DESCRIPTION +A collection of one or more Performance Co-Pilot (PCP) archive +logs may be combined with a control file to produce a PCP archive folio. +Archive folios are created using either +.BR mkaf (1) +or the interactive ``record mode'' services of PCP clients like +.BR pmchart (1). +.PP +.B pmafm +provides a number of services that may be used to process folios. +In particular, it provides support for execution of PCP tools using one +or more of the component +archive logs within an archive folio. +.PP +The target folio is identified by the folio control file +.IR folioname . +The syntax for a folio control file is described in +.BR mkaf (1). +.PP +If present, the command and arguments following +.I folioname +are interpreted and executed as a single command, +otherwise commands are read from standard input. +.PP +The following commands are supported. +.TP +.B archives +Subsequent commands apply to all archives in the folio. +.TP +\f3archives\f1 \f2N\f1[,...] +Archives within a folio are numbered 1, 2, etc. +Subsequent commands are restricted to apply only to +the designated archives. +.TP +\f3archives\f1 \f2name\f1[,...] +Archives within a folio have unique names. +Subsequent commands are restricted to apply only to +the designated archives. +.TP +.B check +Validate the presence and format of each file in the +folio and the component archives. +.TP +.B help +.br +A brief reminder of the command syntax. +.B ? +is a synonym for +.BR help . +.TP +.B hosts +.br +Subsequent commands apply to all archives in the folio. +.TP +\f3hosts\f1 \f2hostname\f1[,...] +Subsequent commands are restricted to apply only to +those archives that match the designated hostnames. +.TP +\f3list\f1 [\f3verbose\f1] +Display the contents of the folio. By default the control header +and the ordinal number, hostname and archive base name for each archive +in the folio. +The +.B verbose +option causes +.B pmafm +to dump the label record from each archive using +.BR "pmdumplog \-l" . +.if t .sp 0.5v +.IP "" +The first named archive in the folio is assumed to be +associated with the default host for any tool that tries to +replay multiple archives from the folio. +.if t .sp +.TP +.BR quit +.br +Exit +.BR pmafm . +.TP +.BR remove +.br +Echo on standard output the +.BR sh (1) +commands required to remove all of the physical files associated with +this archive folio. +.TP +\f3repeat\f1 \f2tool\f1 [\f2arg\f1 ...] +Execute the known PCP +.I tool +once per selected archive. For example, the command +.br +.ti +5n +.ft CW +repeat pmval \-t60 kernel.all.load +.br +would run +.BR pmval (1) +once per archive, with an appropriate +.B \-a +argument. +.TP +.B replay +.br +Some archive folios are created by tools +(e.g. \c +.BR pmchart (1)) +that provide +sufficient information to allow all of the information +in all of the archives of a folio to be replayed. +.TP +[\f3run\f1] \f2tool\f1 [\f2arg\f1 ...] +Execute the known PCP +.I tool +on the selected archives. +Some PCP tools are able to process multiple concurrent +archives, and in this case the tool is run once with +the list of all selected archives passed via a +.B \-a +argument. +Otherwise, this command is synonymous with +.BR repeat . +.TP +.B selections +Display those archives that would be selected for +processing with a +.BR repeat , +.B replay +or +.B run +command. +.PP +The restrictions via any +.B hosts +and +.B archives +commands are conjuncted. +These restrictions serve to limit the specific archives +processed in the subsequent +.BR repeat , +.BR replay , +.B run +and +.B selections +commands. +By default, all archives are selected. +.PP +Keywords in commands may be abbreviated provided no ambiguity +is introduced, e.g. +.BR help , +.B hel +and +.B he +are synonymous, +but +.B h +is ambiguous. +.SH FILES +.PD 0 +.TP 10 +.BI $PCP_SYSCONF_DIR/pmafm/ * +control files that define the behavior of each PCP tool +known to +.BR pmafm . +This information may be customized or extended, see +.I $PCP_SYSCONF_DIR/pmafm/pcp +for documentation of the syntax and semantics of these files. +.TP +.BI $HOME/.pcp/pmafm/ * +User customization of the control files. All files in this +directory are treated in the same manner as control files in +the +.I $PCP_SYSCONF_DIR/pmafm +directory. +.PD +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.I /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). +.SH SEE ALSO +.PP +.BR mkaf (1), +.BR pmchart (1), +.BR pmview (1), +.BR PMAPI (3), +.BR pmRecordSetup (3), +.BR pcp.conf (5) +and +.BR pcp.env (5). +.SH DIAGNOSTICS +Many, but all are intended to be easily understood. diff --git a/man/man1/pmatop.1 b/man/man1/pmatop.1 new file mode 100644 index 0000000..3cbbef5 --- /dev/null +++ b/man/man1/pmatop.1 @@ -0,0 +1,212 @@ +.TH PMATOP 1 "PCP" "Performance Co-Pilot" +.SH NAME +.B pmatop +\- System & Process Monitor +.SH SYNOPSIS +Interactive usage: +.P +.B pmatop +[\-g|\-m] [\-L linelen] [\-h host] +[ +.I interval +[ +.I samples +]] +.P +Writing and reading raw logfiles: +.P +.B pmatop +\-w +.I rawfile +[ +.I interval +[ +.I samples +]] +.br +.B pmatop +\-r [ +.I rawfile +] [\-g|\-m] [\-L linelen] [\-h host] +.SH DESCRIPTION +The program +.I pmatop +is an interactive monitor to view the load on a Linux system. +It shows the occupation of the most critical hardware resources +(from a performance point of view) on system level, i.e. cpu, memory, disk +and network. By default metrics from the local host are +displayed, but a different host may be specified with the +.I [-h host] +option. It is modeled after +.BR atop (1) +and provides a showcase for the variety of data available via +.BR pmcd (1). +.br +.PP +Every +.I interval +(default: 10 seconds) information is shown about the resource occupation +on system level (cpu, memory, disks and network layers), followed +by a list of processes which have been active during the last interval +If the list of active processes does not entirely fit on +the screen, only the top of the list is shown. +.br +The intervals are repeated till the number of +.I samples +(specified as command argument) is reached, or till the key 'q' is pressed +in interactive mode. +.PP +When +.I pmatop +is started, it checks whether the standard output channel is connected to a +screen, or to a file/pipe. In the first case it produces screen control +codes (via the ncurses library) and behaves interactively; in the second case +it produces flat ASCII-output. +.PP +In interactive mode, the output of +.I pmatop +scales dynamically to the current dimensions of the screen/window. +.PP +Furthermore in interactive mode the output of +.I pmatop +can be controlled by pressing particular keys. +However it is also possible to specify such key as +.B flag +on the command line. In that case +.I pmatop +switches to the indicated mode on beforehand; this mode can +be modified again interactively. Specifying such key as flag is especially +useful when running +.I pmatop +with output to a pipe or file (non-interactively). +These flags are the same as the keys that can be pressed in interactive +mode (see section INTERACTIVE COMMANDS). +.SH OUTPUT FORMAT +The output of +.I pmatop +consists of system level and process level information. The system +level information consists of the following output lines: +.PP +.TP 5 +.B PRC +Process and thread level totals. +.br +This line contains the total cpu time consumed +in system mode (`sys') and in user mode (`user'), +the total number of processes present at this moment (`#proc'), +`sleeping interruptible' (`#tslpi') and `sleeping uninterruptible' (`#tslpu'), +and the number of zombie processes (`#zombie'). +.PP +.TP 5 +.B CPU +The occupation percentage of this process related to the available capacity +for this resource on system level. +.br +This line contains the total CPU usage in system mode, in user mode, +in irq mode, in idle mode, and in wait mode. The +.B cpu +lines contain this information on a per cpu basis. +.PP +.TP 5 +.B CPL +This line contains load average information for the last minute, five +minutes, and fifteen minutes. Also the number of context switches and +the number of device interrupts. +.PP +.TP 5 +.B MEM +This line contains the size of physical memory, free memory, page +cache, buffer cache, and slab. +.PP +.TP 5 +.B SWP +This line contains the size of swap, free swap, committed space, and +committed space limit. +.PP +.TP 5 +.B PAG +This line contains the number of page scans, allocstalls, swapins, and +swapouts. +.PP +.TP 5 +.B LVM/MDD/DSK +For every logical volume/multiple device/hard disk one line is shown +containing the nàme, number of reads, and number of writes. +.PP +.TP 5 +.B NET +The first line is for the upper TCP/IP layer and contains the number +of packets received, packets transmitted, packets received. The next +line is one per network interface and contains the number of packets +received and number of packets transmitted. +.PP +.TP 5 +.B PROCESS +The remaining lines are one line per process and can be controlled as +described below. +.SH INTERACTIVE COMMANDS +When running +.I pmatop +interactively (no output redirection), keys can be pressed to control the +output. +.PP +.TP 5 +.B g +Show generic output (default). + +Per process the following fields are shown in case of a window-width +of 80 positions: +process-id, cpu consumption during +the last interval in system- and user mode, the virtual and resident +memory growth of the process. + +The subsequent columns are the username, number of threads in the +thread group, the status and exit code are shown. +.br +The last columns contain the state, the occupation percentage for the +chosen resource (default: cpu) and the process name. + +When more than 80 positions are available, other information is added. +.PP +.TP 5 +.B m +Show memory related output. + +Per process the following fields are shown in case of a window-width +of 80 positions: +process-id, minor and major +memory faults, size of virtual shared text, total virtual +process size, total resident process size, virtual and resident growth during +last interval, memory occupation percentage and process name. + +When more than 80 positions are available, other information is added. +.PP +Miscellaneous interactive commands: +.PP +.TP 5 +.B ? +Request for help information (also the key 'h' can be pressed). +.PP +.TP 5 +.B z +The pause key can be used to freeze the current situation in order to +investigate the output on the screen. While +.I pmatop +is paused, the keys described above can be pressed to show other +information about the current list of processes. +Whenever the pause key is pressed again, +pmatop will continue with a next sample. +.PP +.SH "SEE ALSO" +.BR PCPIntro (1), +.BR collectl (1), +.BR perl (1), +.BR python (1), +.BR pmlogger (1), +.BR pmcd (1), +.BR pmprobe (1), +.BR pmval (1), +.BR PMAPI (3), +and +.BR pcp.conf (4). + diff --git a/man/man1/pmcd.1 b/man/man1/pmcd.1 new file mode 100644 index 0000000..62e00cc --- /dev/null +++ b/man/man1/pmcd.1 @@ -0,0 +1,1255 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2012-2013 Red Hat. +.\" Copyright (c) 2000 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMCD 1 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmcd\f1 \- performance metrics collector daemon +.SH SYNOPSIS +\f3pmcd\f1 +[\f3\-AfS\f1] +[\f3\-c\f1 \f2config\f1] +[\f3\-C\f1 \f2dirname\f1] +[\f3\-H\f1 \f2hostname\f1] +[\f3\-i\f1 \f2ipaddress\f1] +[\f3\-l\f1 \f2logfile\f1] +[\f3\-L\f1 \f2bytes\f1] +[\f3\-\f1[\f3n\f1|\f3N\f1] \f2pmnsfile\f1] +[\f3\-p\f1 \f2port\f1[,\f2port\f1 ...] +[\f3\-P\f1 \f2passfile\f1] +[\f3\-q\f1 \f2timeout\f1] +[\f3\-s\f1 \f2sockname\f1] +[\f3\-T\f1 \f2traceflag\f1] +[\f3\-t\f1 \f2timeout\f1] +[\f3\-U\f1 \f2username\f1] +[\f3\-x\f1 \f2file\f1] +.SH DESCRIPTION +.B pmcd +is the collector used by the Performance Co-Pilot (see +.BR PCPIntro (1)) +to gather performance metrics +on a system. +As a rule, there must be an instance of +.B pmcd +running on a system for any performance metrics to be available to the +PCP. +.PP +.B pmcd +accepts connections from client applications running either on +the same machine or remotely and provides them with metrics and other related +information from the machine that +.B pmcd +is executing on. +.B pmcd +delegates most of this request servicing to +a collection of Performance Metrics Domain Agents +(or just agents), where each agent is responsible for a particular group of +metrics, known as the domain of the agent. For example the +.B postgresql +agent is responsible for +reporting information relating to the PostgreSQL database, +such as the transaction and query counts, indexing and replication statistics, +and so on. +.PP +The agents may be processes started by +.BR pmcd , +independent processes or Dynamic Shared Objects (DSOs, see +.BR dlopen (3)) +attached to +.BR pmcd 's +address space. +The configuration section below describes how connections to +agents are specified. +.PP +The options to +.B pmcd +are as follows. +.TP +.B \-A +Disable service advertisement. +By default, +.B pmcd +will advertise its presence on the network using any available mechanisms +(such as Avahi/DNS-SD), assisting remote monitoring tools with finding it. +These mechanisms are disabled with this option. +.TP +\f3\-c\f1 \f2config\f1 +On startup +.B pmcd +uses a configuration file from either the +.IR $PCP_PMCDCONF_PATH , +configuration variable in +.IR /etc/pcp.conf , +or an environment variable of the same name. +However, these values may be overridden with +.I config +using this option. +The format of this configuration file is described below. +.TP +\f3\-C\f1 \f2dirname\f1 +Specify the path to the Network Security Services certificate database, +for (optional) secure connections. +The default is +.BR /etc/pki/nssdb . +Refer also to the \f3\-P\f1 option. +If it does not already exist, this database can be created using the +.B certutil +utility. +This process and other certificate database maintenance information +is provided in the +.BR PCPIntro (1) +manual page and the online PCP tutorials. +.TP +.B \-f +By default +.B pmcd +is started as a daemon. +The +.B \-f +option indicates that it should run in the foreground. +This is most useful when trying to diagnose problems with misbehaving +agents. +.TP +\f3\-H\f1 \f2hostname\f1 +This option can be used to set the hostname that +.B pmcd +will use to represent this instance of itself. +This is used by client tools like +.BR pmlogger (1) +when reporting on the (possibly remote) host. +If this option is not set, the pmcd.hostname metric will match that +returned by +.BR pmhostname (1). +Refer to the manual page for that tool for full details on how the hostname is +evaluated. +.TP +\f3\-i\f1 \f2ipaddress\f1 +This option is usually only used on hosts with more than one network +interface. If no +.B \-i +options are specified +.B pmcd +accepts connections made to any of its host's IP (Internet Protocol) addresses. +The +.B \-i +option is used to specify explicitly an IP address that connections should be +accepted on. +.I ipaddress +should be in the standard dotted form (e.g. 100.23.45.6). The +.B \-i +option may be used multiple times to define a list of IP addresses. +Connections made to any other IP addresses the host has will be refused. This +can be used to limit connections to one network interface if the host is a +network gateway. It is also useful if the host takes over the IP address of +another host that has failed. In such a situation only the standard IP +addresses of the host should be given (not the ones inherited from the failed +host). This allows PCP applications to determine that a host has failed, +rather than connecting to the host that has assumed the identity of the failed +host. +.TP +\f3\-l\f1 \f2logfile\f1 +By default a log file named +.I pmcd.log +is written in the directory +.BR $PCP_LOG_DIR/pmcd . +The +.B \-l +option causes the log file to be written to +.I logfile +instead of the default. +If the log file cannot be created or is not writable, output is +written to the standard error instead. +.TP +\f3\-L\f1 \f2bytes\f1 +.IR PDU s +received by +.B pmcd +from monitoring clients are restricted to a +maximum size of 65536 bytes by default to defend against Denial of +Service attacks. The +.B \-L +option may be used to change the maximum incoming +.I PDU +size. +.TP +\f3\-n\f1 \f2pmnsfile\f1 +Normally +.B pmcd +loads the default Performance Metrics Name Space (PMNS) from +.BR $PCP_VAR_DIR/pmns/root , +however if the +.B \-n +option is specified an alternative namespace is loaded +from the file +.IR pmnsfile . +.TP +\f3\-N\f1 \f2pmnsfile\f1 +Same function as +.BR \-n , +except for the handling of +duplicate Performance Metric Identifiers (PMIDs) in +.I pmnsfile +\- duplicates are allowed with +.B \-N +they are not allowed with +.BR \-n . +.TP +\f3\-P\f1 \f2passfile\f1 +Specify the path to a file containing the Network Security Services certificate +database password for (optional) secure connections, and for databases that are +password protected. +Refer also to the \f3\-C\f1 option. +When using this option, great care should be exercised to ensure appropriate +ownership ("pcp" user, typically) and permissions on this file (0400, so as to +be unreadable by any user other than the user running the +.B pmcd +process). +.TP +\f3\-q\f1 \f2timeout\f1 +The pmcd to agent version exchange protocol (new in PCP 2.0 - introduced to +provide backward compatibility) uses this timeout to specify how long pmcd +should wait before assuming that no version response is coming from an agent. +If this timeout is reached, the agent is assumed to be an agent which does +not understand the PCP 2.0 protocol. +The default timeout interval is five seconds, +but the +.B \-q +option allows an alternative timeout interval (which must be greater than +zero) to be specified. The unit of time is seconds. +.TP +.B \-S +Require that all client connections provide user credentials. +This means that only unix domain sockets, or authenticated connections are +permitted (requires secure sockets support). +If any user or group access control requirements are specified in the pmcd +configuration file, then this mode of operation is automatically entered, +whether the \f3\-S\f1 flag is specified or not. +.TP +\f3\-s\f1 \f2sockname\f1 +Specify the path to a local unix domain socket (for platforms supporting this +socket family only). +The default value is +.IR $PCP_RUN_DIR/pmcd.socket . +.TP +\f3\-t\f1 \f2timeout\f1 +To prevent misbehaving clients or agents from hanging the entire Performance Metrics +Collection System (PMCS), +.B pmcd +uses timeouts on PDU exchanges with clients and agents running as processes. +By +default the timeout interval is five seconds. +The +.B \-t +option allows an alternative timeout interval in seconds to be specified. +If +.I timeout +is zero, timeouts are turned off. +It is almost impossible to use the debugger +interactively on an agent unless timeouts have been turned off for its "parent" +.BR pmcd . +.RS +.PP +Once +.B pmcd +is running, the timeout may be dynamically +modified by storing an integer value (the timeout in seconds) +into the metric +.B pmcd.control.timeout +via +.BR pmstore (1). +.RE +.TP +\f3\-T\f1 \f2traceflag\f1 +To assist with error diagnosis for agents and/or clients of +.B pmcd +that are not behaving correctly, an internal event tracing +mechanism is supported within +.BR pmcd . +The value of +.I traceflag +is interpreted as a bit field with the following control functions: +.RS +.TP 4n +.PD 0 +.B 1 +enable client connection tracing +.TP +.B 2 +enable PDU tracing +.TP +.B 256 +unbuffered event tracing +.PD +.PP +By default, event tracing is buffered using +a circular buffer that is over-written as new +events are recorded. The default +buffer size holds the last 20 events, although this number +may be over-ridden by using +.BR pmstore (1) +to modify the metric +.BR "pmcd.control.tracebufs" . +.PP +Similarly once +.B pmcd +is running, the event tracing control +may be dynamically +modified by storing 1 (enable) or +0 (disable) into the metrics +.BR pmcd.control.traceconn , +.B pmcd.control.tracepdu +and +.BR pmcd.control.tracenobuf . +These metrics map to the bit fields associated with the +.I traceflag +argument for the +.B \-T +option. +.PP +When operating in buffered mode, +the event trace buffer will be dumped whenever an agent connection is +terminated by +.BR pmcd , +or when any value is stored into the metric +.B pmcd.control.dumptrace +via +.BR pmstore (1). +.PP +In unbuffered mode, +.B every +event will be reported when it occurs. +.RE +.TP +\f3\-U\f1 \f2username\f1 +User account under which to run +.BR pmcd . +The default is the unprivileged "pcp" account in current versions of PCP, +but in older versions the superuser account ("root") was used by default. +.TP +\f3\-x\f1 \f2file\f1 +Before the +.B pmcd +.I logfile +can be opened, +.B pmcd +may encounter a fatal error which prevents it from starting. By default, the +output describing this error is sent to +.B /dev/tty +but it may redirected to +.IR file . +.PP +If a PDU exchange with an agent times out, the agent has violated the +requirement that it delivers metrics with little or no delay. +This is deemed a +protocol failure and the agent is disconnected from +.BR pmcd . +Any subsequent requests for information from the agent will fail with a status +indicating that there is no agent to provide it. +.PP +It is possible to specify access control to +.B pmcd +based on users, groups and hosts. +This allows one to prevent users, groups of users, and certain hosts from +accessing the metrics provided by +.B pmcd +and is described in more detail in the Section on ACCESS CONTROL below. +.SH CONFIGURATION +On startup +.B pmcd +looks for a configuration file named +.IR $PCP_PMCDCONF_PATH . +This file specifies which agents cover which performance metrics domains and +how +.B pmcd +should make contact with the agents. +An optional section specifying access controls may follow the agent +configuration data. +.PP +\f3Warning\f1: +.B pmcd +is usually started as part of the boot sequence and runs initially as root. +The configuration file may contain shell commands to create agents, +which will be executed by root. +To prevent security breaches the configuration file should +be writable only by root. +The use of absolute path names is also recommended. +.PP +The case of the reserved words in the configuration file is unimportant, but +elsewhere, the case is preserved. +.PP +Blank lines and comments are permitted (even encouraged) in the configuration +file. +A comment begins with a ``#'' +character and finishes at the end of the line. +A line may be continued by +ensuring that the last character on the line is a ``\\'' +(backslash). +A comment on a continued line ends at the end of the continued +line. +Spaces may be included in lexical elements by enclosing the entire +element in double quotes. +A double quote preceded by a backslash is always a +literal double quote. +A ``#'' +in double quotes or preceded by a backslash is treated literally rather than as +a comment delimiter. +Lexical elements and separators are described further in +the following sections. +.SH "AGENT CONFIGURATION" +Each line of the agent configuration section of the configuration file contains +details of how to connect +.B pmcd +to one of its agents and specifies which metrics domain the agent deals with. +An agent may be attached as a DSO, or via a socket, or a pair +of pipes. +.PP +Each line of the agent configuration section of the configuration file must be +either an agent specification, a comment, or a blank line. +Lexical elements +are separated by whitespace characters, however a single agent specification +may not be broken across lines unless a +.B \\\\\& +(backslash) is used to continue the line. +.PP +Each agent specification must start with a textual label (string) followed by +an integer in the range 1 to 510. +The label is a tag used to refer to the +agent and the integer specifies the domain for which the agent supplies data. +This domain identifier corresponds to the domain portion of the PMIDs handled +by the agent. +Each agent must have a unique label and domain identifier. +.PP +For DSO agents a line of the form: +.TP +\& +\f2label\f1 \f2domain-no\f1 \f3dso\f1 \f2entry-point\f1 \f2path\f1 +.PP +should appear. +Where, +.TP 14 +.PD 0 +.I label +is a string identifying the agent +.TP 14 +.I domain-no +is an unsigned integer specifying the agent's domain in the range 1 to 510 +.TP 14 +.I entry-point +is the name of an initialization function which will be called when the DSO is +loaded +.TP 14 +.I path +designates the location of the DSO and this is expected +to be an absolute pathname. +.B pmcd +is only able to load DSO agents that have the same +.I simabi +(Subprogram Interface Model ABI, or calling conventions) as it does (i.e. only +one of the +.I simabi +versions will be applicable). The +.I simabi +version of a running +.B pmcd +may be determined by fetching +.BR pmcd.simabi . +Alternatively, the +.BR file (1) +command may be used to determine the +.I simabi +version from the +.B pmcd +executable. +.PD +.IP "" 14 +For a relative +.I path +the environment variable +.B PMCD_PATH +defines a colon (:) separated list of directories to search +when trying to locate the agent DSO. The default +search path is +.BR "$PCP_SHARE_DIR/lib:/usr/pcp/lib" . +.PP +For agents providing socket connections, a line of the form +.TP +\& +\f2label\f1 \f2domain-no\f1 \f3socket\f1 \f2addr-family\f1 \f2address\f1 [ \f2command\f1 ] +.PP +should appear. +Where, +.TP 14 +.PD 0 +.I label +is a string identifying the agent +.TP 14 +.I domain-no +is an unsigned integer specifying the agent's domain in the range 1 to 510 +.TP 14 +.I addr-family +designates whether the socket is in the +.B AF_INET, +.B AF_INET6 +or +.B AF_UNIX +domain, and the corresponding +values for this parameter are +.B inet, +.B ipv6 +and +.B unix +respectively. +.TP 14 +.I address +specifies the address of the socket within the previously +specified +.I addr-family. +For +.B unix +sockets, the address should be the name of an agent's socket on the +local host (a valid address for the UNIX domain). +For +.B inet +and +.B ipv6 +sockets, the address may be either a port number or a port name which may be +used to connect to an agent on the local host. +There is no syntax for +specifying an agent on a remote host as a +.B pmcd +deals only with agents on the same machine. +.TP 14 +.I command +is an optional parameter used to specify a command line to start the agent when +.B pmcd +initializes. +If +.I command +is not present, +.B pmcd +assumes that the specified agent has +already been created. +The +.I command +is considered to start from the first non-white character after the socket +address and finish at the next newline that isn't preceded by a backslash. +After a +.BR fork (2) +the +.I command +is passed unmodified to +.BR execve (2) +to instantiate the agent. +.PD +.PP +For agents interacting with the +.B pmcd +via stdin/stdout, a line of the form: +.TP +\& +\f2label\f1 \f2domain-no\f1 \f3pipe\f1 \f2protocol\f1 \f2command\f1 +.PP +should appear. +Where, +.TP 14 +.PD 0 +.I label +is a string identifying the agent +.TP 14 +.I domain-no +is an unsigned integer specifying the agent's domain +.TP 14 +.I protocol +The value for this parameter should be +.BR binary . +.sp +.IP +Additionally, the \f2protocol\fP can include the \f3notready\fP keyword +to indicate that the agent must be marked as not being ready to process +requests from \f3pmcd\f1. The agent will explicitly notify the \f3pmcd\fP +when it is ready to process the requests by sending \f3PM_ERR_PMDAREADY\fP +PDU. +.PD +.TP 14 +.I command +specifies a command line to start the agent when +.B pmcd +initializes. +Note that +.I command +is mandatory for pipe-based agents. +The +.I command +is considered to start from the first non-white character after the +.I protocol +parameter and finish at the next newline that isn't preceded by a backslash. +After a +.BR fork (2) +the +.I command +is passed unmodified to +.BR execve (2) +to instantiate the agent. +.SH "ACCESS CONTROL CONFIGURATION" +The access control section of the configuration file is optional, but if +present it must follow the agent configuration data. +The case of reserved words is ignored, but elsewhere case is preserved. +Lexical elements in the access control section are separated by whitespace +or the special delimiter characters: +square brackets (``['' and ``]''), +braces (``{'' and ``}''), +colon (``:''), +semicolon (``;'') +and +comma (``,''). +The special characters are not treated as special in the agent configuration +section. +Lexical elements may be quoted (double quotes) as necessary. +.PP +The access control section of the file must start with a line of the form: +.TP +.B [access] +.PP +Leading and trailing whitespace may appear around and within the brackets and +the case of the +.B access +keyword is ignored. +No other text may appear on the line except a trailing comment. +.PP +Following this line, the remainder of the configuration file should contain +lines that allow or disallow operations from particular hosts or groups of +hosts. +.PP +There are two kinds of operations that occur via +.BR pmcd : +.TP 15 +.B fetch +allows retrieval of information from +.BR pmcd . +This may be information about a metric (e.g. its description, instance domain +or help text) or a value for a metric. +.TP 15 +.B store +allows +.B pmcd +to be used to store metric values in agents that permit store operations. +This may be the actual value of the metric (e.g. resetting a counter to +zero). Alternatively, it may be a value used by the PMDA to introduce a +change to some aspect of monitoring of that metric (e.g. server side event +filtering) \- possibly even only for the active client tool performing the +store operation, and not others. +.PP +Access to +.B pmcd +can be granted in three ways - by user, group of users, or at a host level. +In the latter, all users on a host are granted the same level of access, +unless the user or group access control mechanism is also in use. +.PP +User names and group names will be verified using the local +.B /etc/passwd +and +.B /etc/groups +files (or an alternative directory service), using the +.BR getpwent (3) +and +.BR getgrent (3) +routines. +.PP +Hosts may be identified by name, IP address, IPv6 address or by the special host +specifications ``"unix:"'' or ``"local:"''. ``"unix:"'' refers to +.B pmcd's +unix domain socket, on supported platforms. ``"local:"'' is equivalent to +specifying ``"unix:"'' and ``localhost``. +.PP +Wildcards may also be specified by ending the host identifier with the +single wildcard character ``*'' as the last-given component of an +address. The wildcard ``".*"'' refers to all inet (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. +.PP +The wildcard ``*'' refers to all users, groups or host addresses, +including ``"unix:"''. +Names of users, groups or hosts may not be wildcarded. +.PP +The following are all valid host identifiers: +.de CS +.in +0.5i +.ft CW +.nf +.. +.de CE +.fi +.ft 1 +.in +.. +.PP +.CS +boing +localhost +giggle.melbourne.sgi.com +129.127.112.2 +129.127.114.* +129.* +\&.* +fe80::223:14ff:feaf:b62c +fe80::223:14ff:feaf:* +fe80:* +:* +"unix:" +"local:" +* +.CE +.PP +The following are not valid host identifiers: +.PP +.CS +*.melbourne +129.127.*.* +129.*.114.9 +129.127* +fe80::223:14ff:*:* +fe80::223:14ff:*:b62c +fe80* +.CE +.PP +The first example is not allowed because only (numeric) IP addresses may +contain a wildcard. +The second and fifth examples are not valid because there is more than +one wildcard character. +The third and sixth contain an embedded wildcard, the fourth and seventh +have a wildcard character that is not the last component of +the address (the last components are \f(CW127*\f1 and \f(CWfe80*\f1 respectively). +.PP +The name +.B localhost +is given special treatment to make the behavior of host wildcarding +consistent. +Rather than being 127.0.0.1 and ::1, it is mapped to the primary inet and IPv6 addresses +associated with the name of the host on which +.B pmcd +is running. +Beware of this when running +.B pmcd +on multi-homed hosts. +.PP +Access for users, groups or hosts are allowed or disallowed by specifying +statements of the form: +.TP +\& +\f3allow users\f1 \f2userlist\f1 \f3:\f1 \f2operations\f1 \f3;\f1 +.br +\f3disallow users\f1 \f2userlist\f1 \f3:\f1 \f2operations\f1 \f3;\f1 +.br +\f3allow groups\f1 \f2grouplist\f1 \f3:\f1 \f2operations\f1 \f3;\f1 +.br +\f3disallow groups\f1 \f2grouplist\f1 \f3:\f1 \f2operations\f1 \f3;\f1 +.br +\f3allow hosts\f1 \f2hostlist\f1 \f3:\f1 \f2operations\f1 \f3;\f1 +.br +\f3disallow hosts\f1 \f2hostlist\f1 \f3:\f1 \f2operations\f1 \f3;\f1 +.PP +.TP 14 +.IR list +.IR userlist , +.I grouplist +and +.I hostlist +are comma separated lists of one or more users, groups or host identifiers. +.TP 14 +.I operations +is a comma separated list of the operation types described above, +.B all +(which allows/disallows all operations), or +.B all except +.I operations +(which allows/disallows all operations except those listed). +.PP +Either plural or singular forms of +.BR users , +.BR groups , +and +.B hosts +keywords are allowed. +If this keyword is omitted, a default of +.B hosts +will be used. +This behaviour is for backward-compatibility only, it is preferable to be explicit. +.PP +Where no specific +.B allow +or +.B disallow +statement applies to an operation, the default is to allow the +operation from all users, groups and hosts. +In the trivial case when there is no access control section in +the configuration file, all operations from all users, groups, +and hosts are permitted. +.PP +If a new connection to +.B pmcd +is attempted by a user, group or host that is not permitted to perform any +operations, the connection will be closed immediately after an error response +.B PM_ERR_PERMISSION +has been sent to the client attempting the connection. +.PP +Statements with the same level of wildcarding specifying identical hosts may +not contradict each other. +For example if a host named +.B clank +had an IP address of 129.127.112.2, specifying the following two rules would be +erroneous: +.PP +.CS +allow host clank : fetch, store; +disallow host 129.127.112.2 : all except fetch; +.CE +.PP +because they both refer to the same host, but disagree as to whether the +.B fetch +operation is permitted from that host. +.PP +Statements containing more specific host specifications override less specific +ones according to the level of wildcarding. +For example a rule of the form +.PP +.CS +allow host clank : all; +.CE +.PP +overrides +.PP +.CS +disallow host 129.127.112.* : all except fetch; +.CE +.PP +because the former contains a specific host name (equivalent to a fully +specified IP address), whereas the latter has a wildcard. +In turn, the latter would override +.PP +.CS +disallow host * : all; +.CE +.PP +It is possible to limit the number of connections from a user, group or host to +.BR pmcd . +This may be done by adding a clause of the form +.TP +\& +\f3maximum\f1 \f2n\f1 \f3connections\f1 +.PP +to the +.I operations +list of an +.B allow +statement. +Such a clause may not be used in a +.B disallow +statement. +Here, +.I n +is the maximum number of connections that will be accepted from the user, group +or host matching the identifier(s) used in the statement. +.PP +An access control statement with a list of user, group or host identifiers is +equivalent to a set of access control statements, with each specifying one of +the identifiers in the list and all with the same access controls (both permissions +and connection limits). +A group should be used if you want users to contribute to a shared connection limit. +A wildcard should be used if you want hosts to contribute to a shared connection limit. +.PP +When a +new client requests a connection, and +.B pmcd +has determined that the client has permission to connect, it searches the +matching list of access control statements for the most specific match +containing a connection limit. +For brevity, this will be called the limiting +statement. +If there is no limiting statement, the client is granted a +connection. +If there is a limiting statement and the number of +.B pmcd +clients with user ID, group ID, or IP addresses that match the identifier in +the limiting statement is less than the connection limit in the statement, +the connection is allowed. +Otherwise the connection limit has been reached and the client is +refused a connection. +.PP +Group access controls and the wildcarding in host identifiers means that once +.B pmcd +actually accepts a connection from a client, the connection may contribute to +the current connection count of more than one access control statement \- the +client's host may match more than one access control statement, and similarly +the user ID may be in more than one group. +This may be significant for subsequent connection requests. +.PP +Note that +.B pmcd +enters a mode where it runs effectively with a higher-level of security as +soon as a user or group access control section is added to the configuration. +In this mode only authenticated connections are allowed \- either from a SASL +authenticated connection, or a Unix domain socket (which implicitly passes +client credentials). +This is the same mode that is entered explicitly using the \f3\-S\f1 option. +Assuming permission is allowed, one can determine whether +.B pmcd +is running in this mode by querying the value of the +.I pmcd.feature.creds_required +metric. +.PP +Note also that because most specific match semantics are used when checking the +connection limit, for the host-based access control case, priority is given +to clients with more specific host identifiers. +It is also possible to exceed connection limits in some situations. +Consider the following: +.IP +allow host clank : all, maximum 5 connections; +.br +allow host * : all except store, maximum 2 connections; +.PP +This says that only 2 client connections at a time are permitted for all +hosts other than "clank", which is permitted 5. +If a client from host "boing" is the first to connect to +.BR pmcd , +its connection is checked against the second statement (that is the most +specific match with a connection limit). +As there are no other clients, the +connection is accepted and contributes towards the limit for only the second +statement above. +If the next client connects from "clank", its connection is +checked against the limit for the first statement. +There are no other +connections from "clank", so the connection is accepted. +Once this connection +is accepted, it counts towards +.B both +statements' limits because "clank" matches the host identifier in both +statements. +Remember that the decision to accept a new connection is made +using only the most specific matching access control statement with a +connection limit. +Now, the connection limit for the second statement has been +reached. +Any connections from hosts other than "clank" will be refused. +.PP +If instead, +.B pmcd +with no clients saw three successive connections arrived from "boing", the +first two would be accepted and the third refused. +After that, if a connection +was requested from "clank" it would be accepted. +It matches the first +statement, which is more specific than the second, so the connection limit in +the first is used to determine that the client has the right to connect. +Now +there are 3 connections contributing to the second statement's connection +limit. +Even though the connection limit for the second statement has been +exceeded, the earlier connections from "boing" are maintained. +The connection +limit is only checked at the time a client attempts a connection rather than +being re-evaluated every time a new client connects to +.BR pmcd . +.PP +This gentle scheme is designed to allow reasonable limits to be imposed +on a first come first served basis, with specific exceptions. +.PP +As illustrated by the example above, a client's connection is honored once it +has been accepted. +However, +.B pmcd +reconfiguration (see the next section) re-evaluates all the connection counts +and will cause client connections to be dropped where connection limits have +been exceeded. +.SH "RECONFIGURING PMCD" +If the configuration file has been changed or if an agent is not responding +because it has terminated or the PMNS has been changed, +.B pmcd +may be reconfigured by sending it a SIGHUP, as in +.PP +.CS +# pmsignal \-a \-s HUP pmcd +.CE +.PP +When +.B pmcd +receives a SIGHUP, it checks the configuration file for changes. +If the file +has been modified, it is reparsed and the contents become the new +configuration. +If there are errors in the configuration file, the existing +configuration is retained and the contents of the file are ignored. +Errors are reported in the +.B pmcd +log file. +.PP +It also checks the PMNS file for changes. If the PMNS file has been +modified, then it is reloaded. +Use of +.BR tail (1) +on the log file is recommended while reconfiguring +.BR pmcd . +.PP +If the configuration for an agent has changed (any parameter except the agent's +label is different), the agent is restarted. +Agents whose configurations do not change are not +restarted. +Any existing agents +not present in the new configuration are terminated. +Any deceased agents are that are still listed are +restarted. +.PP +Sometimes it is necessary to restart an agent that is still running, but +malfunctioning. +Simply stop the agent (e.g. using SIGTERM from +.BR pmsignal (1)), +then send +.B pmcd +a SIGHUP, which will cause the agent to be restarted. +.SH "STARTING AND STOPPING PMCD" +Normally, +.B pmcd +is started automatically at boot time and stopped when the +system is being brought down (see +.BR rc2 (1M) +and +.BR rc0 (1M)). +Under certain circumstances it is necessary to start or stop +.B pmcd +manually. +To do this one must become superuser and type +.PP +.CS +# $PCP_RC_DIR/pcp start +.CE +.PP +to start +.BR pmcd , +or +.PP +.CS +# $PCP_RC_DIR/pcp stop +.CE +.PP +to stop +.BR pmcd . +Starting +.B pmcd +when it is already running is the same as stopping +it and then starting it again. +.PP +Sometimes it may be necessary to restart +.B pmcd +during another phase of the boot process. +Time-consuming parts of the boot +process are often put into the background to allow the system to become +available sooner (e.g. mounting huge databases). +If an agent run by +.B pmcd +requires such a task to complete before it can run properly, it is necessary to +restart or reconfigure +.B pmcd +after the task completes. +Consider, for example, the case of mounting a +database in the background while booting. +If the PMDA which provides the +metrics about the database cannot function until the database is mounted and +available but +.B pmcd +is started before the database is ready, the PMDA will fail (however +.B pmcd +will still service requests for metrics from other domains). +If the database +is initialized by running a shell script, adding a line to the end of the +script to reconfigure +.B pmcd +(by sending it a SIGHUP) will restart the PMDA (if it exited because it +couldn't connect to the database). +If the PMDA didn't exit in such a situation +it would be necessary to restart +.B pmcd +because if the PMDA was still running +.B pmcd +would not restart it. +.P +Normally +.B pmcd +listens for client connections on TCP/IP port number 44321 +(registered at +.IR http://www.iana.org/ ). +Either the environment +variable +.B PMCD_PORT +or the +.B \-p +command line option +may be used to specify alternative port number(s) when +.B pmcd +is started; in each case, the specification is a comma-separated list +of one or more numerical port numbers. Should both methods be used +or multiple +.B \-p +options appear on the command line, +.B pmcd +will listen on the union of the set of ports specified via all +.B \-p +options and the +.B PMCD_PORT +environment variable. +If non-default ports are used with +.B pmcd +care should be taken to ensure that +.B PMCD_PORT +is also set in the environment of any client application that +will connect to +.BR pmcd , +or that the extended host specification syntax is used +(see +.BR PCPIntro (1) +for details). +.SH FILES +.PD 0 +.TP 10 +.I $PCP_PMCDCONF_PATH +default configuration file +.TP +.I $PCP_PMCDOPTIONS_PATH +command line options to +.B pmcd +when launched from +.B $PCP_RC_DIR/pcp +All the command line option lines should start with a hyphen as +the first character. +This file can also contain environment variable settings of +the form "VARIABLE=value". +.TP +.B \&./pmcd.log +(or +.B $PCP_LOG_DIR/pmcd/pmcd.log +when started automatically) +.TP +.B $PCP_RUN_DIR/pmcd.pid +contains an ascii decimal representation of the process ID of +.B pmcd +, when it's running. +.br +All messages and diagnostics are directed here +.TP +.B /etc/pki/nssdb +default Network Security Services (NSS) certificate database +directory, used for optional Secure Socket Layer connections. +This database can be created and queried using the NSS +.B certutil +tool, amongst others. +.TP +.B /etc/passwd +user names, user identifiers and primary group identifiers, used for access control specifications +.TP +.B /etc/groups +group names, group identifiers and group members, used for access control specifications +.PD +.SH ENVIRONMENT +In addition to the PCP environment variables described in the +.B "PCP ENVIRONMENT" +section below, the +.B PMCD_PORT +variable is also recognised +as the TCP/IP port for incoming connections +(default +.IR 44321 ), +and the +.B PMCD_SOCKET +variable is also recognised +as the path to be used for the Unix domain socket. +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.B /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). +.SH DIAGNOSTICS +If +.B pmcd +is already running the message "Error: OpenRequestSocket bind: Address may already be in use" will appear. +This may also appear if +.B pmcd +was shutdown with an outstanding request from a client. +In this case, a +request socket has been left in the TIME_WAIT state and until the system closes +it down (after some timeout period) it will not be possible to run +.BR pmcd . +.PP +In addition to the standard +.B PCP +debugging flags, see +.BR pmdbg (1), +.B pmcd +currently uses +.B DBG_TRACE_APPL0 +for tracing I/O and termination of agents, +.B DBG_TRACE_APPL1 +for tracing access control and +.B DBG_TRACE_APPL2 +for tracing the configuration file scanner and parser. +.SH CAVEATS +.B pmcd +does not explicitly terminate its children (agents), it only +closes their pipes. +If an agent never checks for a closed pipe it may not terminate. +.PP +The configuration file parser will only read lines of less than 1200 +characters. +This is intended to prevent accidents with binary files. +.PP +The timeouts controlled by the +.B \-t +option apply to IPC between +.B pmcd +and the PMDAs it spawns. This is independent of settings of the +environment variables +.B PMCD_CONNECT_TIMEOUT +and +.B PMCD_REQUEST_TIMEOUT +(see +.BR PCPIntro (1)) +which may be used respectively to control timeouts for client applications +trying to connect to +.B pmcd +and trying to receive information from +.BR pmcd . +.SH SEE ALSO +.BR PCPIntro (1), +.BR pmdbg (1), +.BR pmerr (1), +.BR pmgenmap (1), +.BR pminfo (1), +.BR pmstat (1), +.BR pmstore (1), +.BR pmval (1), +.BR getpwent (3), +.BR getgrent (3), +.BR pcp.conf (5), +and +.BR pcp.env (5). diff --git a/man/man1/pmcd_wait.1 b/man/man1/pmcd_wait.1 new file mode 100644 index 0000000..9aab2c2 --- /dev/null +++ b/man/man1/pmcd_wait.1 @@ -0,0 +1,123 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMCD_WAIT 1 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmcd_wait\f1 \- wait for PMCD to accept client connections +.\" literals use .B or \f3 +.\" arguments use .I or \f2 +.SH SYNOPSIS +\f3$PCP_BINADM_DIR/pmcd_wait\f1 +[\f3-h\f1 \f2host\f1] +[\f3-t\f1 \f2interval\f1] +[\f3\-v\f1] +.SH DESCRIPTION +.B pmcd_wait +waits for the Performance +Metrics Collector Daemon (PMCD) to be running and accepting client connections. +.P +Unless directed to another host by the +.B \-h +option, +.B pmcd_wait +will try to contact +.BR pmcd (1) +on the local host. +.P +.B pmcd_wait +will timeout and abandon the attempt to connect to +.B pmcd +after 60 seconds. This default timeout interval +may be changed using the +.B \-t +option, where the +.I interval +argument follows the syntax described in +.BR PCPIntro (1) +and in the simplest form may be an unsigned integer (the implied +units in this case are seconds). +.P +On successful connection to +.B pmcd +an exit status of zero is returned. +.PP +If an error or timeout occurs, then a non-zero exit status is returned +as described below. +.PP +The other options are as follows: +.TP +.B \-v +This option turns the verbose mode on. +With the verbose mode off +(which is the default), no output will be generated. +With verbose mode on, error messages will be output on +.IR stderr . +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.I /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). +.SH SEE ALSO +.BR PCPIntro (1), +.BR pmcd (1), +.BR pcp.conf (5) +and +.BR pcp.env (5). +.SH DIAGNOSTICS +Error messages will be output to +.I stderr +only if the verbose mode is on. +.P +The following exit status codes are returned: +.TP +.B 0 +.B pmcd_wait +was able to successfully connect to +.B pmcd +within the timeout period. +.TP +.B 1 +A usage error occurred, use +.B \-v +for more details. +.TP +.B 2 +No connection was made in the timeout interval. +This will happen if +.B pmcd +is running but +takes too long to complete the client connection, or if +.B pmcd +is not running and all connection attempts in the timeout +interval failed with the error ECONNREFUSED. +.TP +.B 3 +A U\s-2NIX\s+2 error occurred, use +.B \-v +for more details. +.TP +.B 4 +A PCP error occurred, use +.B \-v +for more details. diff --git a/man/man1/pmchart.1 b/man/man1/pmchart.1 new file mode 100644 index 0000000..3cd2a40 --- /dev/null +++ b/man/man1/pmchart.1 @@ -0,0 +1,655 @@ +.\" Copyright (c) 2006, Ken McDonell. All Rights Reserved. +.\" Copyright (c) 2008, Aconex. All Rights Reserved. +.\" Copyright (c) 2014, Red Hat. +.TH PMCHART 1 "" "Performance Co-Pilot" +.SH NAME +\f3pmchart\f1 \- strip chart tool for Performance Co-Pilot +.SH SYNOPSIS +\f3pmchart\f1 +[\f3\-CVWz\f1] +[\f3\-A\f1 \f2align\f1] +[\f3\-a\f1 \f2archive\f1] +[\f3\-c\f1 \f2configfile\f1] +[\f3\-f\f1 \f2fontfamily\f1] +[\f3\-F\f1 \f2fontsize\f1] +[\f3\-g\f1 \f2geometry\f1] +[\f3\-g\f1 \f2geometry\f1] +[\f3\-h\f1 \f2host\f1] +[\f3\-o\f1 \f2outfile\f1] +[\f3\-O\f1 \f2offset\f1] +[\f3\-p\f1 \f2port\f1] +[\f3\-s\f1 \f2samples\f1] +[\f3\-S\f1 \f2starttime\f1] +[\f3\-T\f1 \f2endtime\f1] +[\f3\-t\f1 \f2interval\f1] +[\f3\-v\f1 \f2visible\f1] +[\f3\-Z\f1 \f2timezone\f1] +[\f2sources\f1...] +.SH DESCRIPTION +.B pmchart +is a graphical utility that plots performance metrics values +available through the facilities of the Performance Co-Pilot (PCP). +Multiple charts can be displayed simultaneously, either aligned +on the unified time axis (X-axis), and through the use of multiple +interface Tabs. +.PP +Metric values can be sourced from one or more live hosts +(simultaneously). Alternatively, one or more PCP archives +can be used as a source of historical data. +See +.BR PCPIntro (1) +for an in-depth discussion of the capabilities of the PCP +framework, many of which are used by +.B pmchart. +.PP +Many aspects of the behaviour of +.B pmchart +can be customised through the interface. +In particular, the use of "views" (refer to the section describing +VIEWS later in this document) +allows predefined sets of metrics and charting parameters +like colors, scaling, titles, legends, and so on to be stored for +later use, or use with different hosts and archives. +In addition, the Preferences dialog allows customisations to the +rest of the +.B pmchart +user interface to be saved and restored between different invocations +of the tool. +This allows the default background color, highlight color, contents +and location of the toolbar, and many other aspects to be configured. +.PP +.B pmchart +makes extensive use of the +.BR pmtime (1) +utility for time control, refer to the +.B pmtime +manual page for further details of its operation. +.PP +Options which control the default source, timing and layout of the +.B pmchart +window are as follows: +.TP 5 +.B \-a +Performance metric values are retrieved from the Performance Co-Pilot +(PCP) archive log file identified by the base name archive, by default. +The initial Tab created will be an archive mode Tab. +Multiple +.B \-a +options can be presented, and the list of archives is used for sourcing +metric values. +Any \f2sources\f1 listed on the command line are assumed to be archives +if this option is used. +.TP +.B \-c +.I configfile +specifies an initial view to load, using the default source of metrics. +Multiple +.B \-c +views can be specified, and they will all be opened in the +default Tab with the default source of metrics. +.TP +.B \-C +Used with +.BR \-c , +the view(s) are parsed, any errors are reported, and the tool exits. +This is primarily intended for testing purposes. +If a second +.B \-C +option is presented, +.B pmchart +also connects to +.BR pmcd (1) +to check the semantics of metrics. +.TP +.B \-f +Specify the default font +.I family +to be used in several chart components, +such as the chart title, legend, and Y-axis label. +The default value is "Sans Serif". +This setting does not affect the rest of the user interface, where +the value is inherited from the environment in which +.B pmchart +operates, and differs according to the look-and-feel of each +platform. +.TP +.B \-F +Specify the default font +.I point +size to be used in several chart components, +such as the chart title, legend, and Y-axis label. +The default is platform dependent, but is either 7, 8 or 9. +This setting does not affect the rest of the user interface. +.TP +.B \-g +Generate image with the specified +.I geometry +(width and height). +This option is only useful when used in conjunction with the +.B \-o +option for generating an output image. +The +.I geometry +argument takes the form "WxH" (e.g. 240x120). +.TP +.B \-h +Current performance metric values are retrieved from the nominated +.I host +machine by default. +Multiple +.B \-h +options can be presented, and the list of hosts is used for sourcing +metric values. +Any \f2sources\f1 listed on the command line are assumed to be hosts +if this option is used. +.TP +.B \-o +Generate an image file named +.IR outfile , +and then exit. +This is most useful when run with an archive and one or more views. +The generated image will be in the format specified as the file +extension (automatically determined from +.IR outfile ). +If no extension can be determined, then the GIF format is used and +the generated file is named with this extension. +The supported image file formats include: bmp, jpeg, jpg, png, ppm, +tif, tiff, xbm, and xpm. +.TP +.B \-p +.I port +number for connection to an existing +.B pmtime +time control process. +.TP +.B \-s +Specifies the number of +.I samples +that will be retained before discarding old data (replaced by +new values at the current time position). +This value can subsequently be modified through the Edit Tab +dialog. +.TP +.B \-t +Sets the inital update +.I interval +to something other than the default 1 second. +The +.I interval +argument follows the syntax described in +.BR PCPIntro (1), +and in the simplest form may be an unsigned integer (the implied +units in this case are seconds). +.TP +.B \-v +Sets the inital visible +.I samples +that will be displayed in all charts in the default Tab. +This value must be less than or equal to the total number +of samples retained (the +.B \-s +value). +.TP +.B \-V +Display pmchart version number and exit +.TP +.B \-W +Export images using an opaque(white) background +.TP +.B \-Z +By default, +.B pmtime +reports the time of day according to the local timezone on the system +where +.B pmchart is run. +The +.B \-Z +option changes the timezone to +.I timezone +in the format of the environment variable TZ as described in +.BR environ (5). +.TP +.B \-z +Change the reporting timezone to the local timezone at the host +that is the source of the performance metrics, as identified via +either the +.B \-h +or +.B \-a +options. +.PP +The +.BR \-S , +.BR \-T , +.B \-O +and +.B \-A +options may be used to define a time window to +restrict the samples retrieved, set an initial origin within the time +window, or specify a "natural" alignment of the sample times; refer +to +.BR PCPIntro (1) +for a complete description of these options. +.SH VIEWS +The primary +.B pmchart +configuration file is the "view", which allows the metadata +associated with one or more charts to be saved in the filesystem. +This metadata describes all aspects of the charts, including +which PCP metrics and instances are to be used, which hosts, which +colors, the chart titles, use of chart legends, and much more. +.PP +From a conceptual point of view, there are two classes of view. +These views share the same configuration file format \- refer +to a later section for a complete description of this format. +The differences lie in where they are installed and how they +are manipulated. +.PP +The first class, the "system" view, is simply any view that is +installed as part of the +.B pmchart +package. +These are stored in +.I $PCP_VAR_DIR/config/pmchart. +When the +.I "File\(->Open View" +dialog is displayed, it is these views that are initially listed. +The system views cannot be modified by a normal user, and should +not be modified even by a user with suitable priviledges, as they +will be overwritten during an upgrade. +.PP +The second class of view is the "user" view. +These views are created on-the-fly using the +.I "File\(->Save View" +dialog. +This is a mechanism for individual users to save their commonly +used views. +Access to these views is achieved through the +.I "File\(->Open View" +dialog, as with the system views. +Once the dialog is opened, the list of views can be toggled between +user and system views by clicking on the two toggle buttons in the +top right corner. +User views are stored in +.I $HOME/.pcp/pmchart. +.SH TABS +.B pmchart +provides the common user interface concept of the Tab, which +is most prevalent in modern web browsers. +Tabs allow +.B pmchart +to update many more charts than the available screen real estate +allows, by providing a user interface mechanism to stack (and +switch between) different vertical sets of charts. +Switching between Tabs is achieved by clicking on the Tab labels, +which are located along the top of the display beneath the Menu +and Tool bars). +.PP +Each Tab has a mode of operation (either live or archive \- +.B pmchart +can support both modes simultaneously), the total number of +samples and currently visible points, and a label describing +the Tab which is displayed at the top of the +.B pmchart +window. +New Tabs can be created using the +.I "File\(->Add Tab" +dialog. +.PP +In order to save on vertical screen real estate, note that the user +interface element for changing between different Tabs (and its label) +are only displayed when more than one Tab exists. +A Tab can be dismissed using the +.I "File\(->Close Tab" +menu, which removes the current Tab and any charts it contained. +.SH IMAGES and PRINTING +A static copy of the currently displayed vertical series of charts +can be captured in two ways. +.PP +When the intended display device is the screen, the +.I "File\(->Export" +menu option should be used. +This allows exporting the charts in a variety of image formats, +including PNG, JPEG, GIF, and BMP. +The image size can be scaled up or down in any dimension. +.PP +Alternatively, when the intended display device is paper, the +.I "File\(->Print" +menu option can be used. +This supports the usual set of printing options (choice of printer, +grayscale/color, landscape/portrait, scaling to different paper sizes, +etc), +and in addition allows printing to the intermediate printer formats +of PostScript and Portable Document Format (PDF). +.SH RECORDING +It is possible to make a recording of a set of displayed charts, +for later playback through +.B pmchart +or any of the other Performance Co-Pilot tools. +The +.I "Record\(->Start" +functionality is simple to configure through the user interface, +and allows fine-tuning of the recording process (including record +frequencies that differ to the +.B pmchart +update interval, alternate file locations, etc). +.PP +.B pmchart +produces recordings that are compatible with the PCP +.BR pmafm (1) +replay mechanism, for later playback via a new instance of +.BR pmchart . +In addition, when recording through +.B pmchart +one can also replay the recording immediately, as on termination +of the recording (through the +.I "Record\(->Stop" +menu item), an archive mode Tab will be created with the captured view. +.PP +Once recording is active in a Live Tab, the Time Control status +button in the bottom left corner of the +.B pmchart +window is displayed with a distinctive red dot. +At any time during a +.B pmchart +recording session, the amount of space used in the filesystem by +that recording can be displayed using the +.I "Record\(->Query" +menu item. +.PP +Finally, the +.I "Record\(->Detach" +menu option provides a mechanism whereby the recording process can +be completely divorced from the running +.B pmchart +process, and allowed to continue on when +.B pmchart +exits. +A dialog displaying the current size and estimated rate of growth for +the recording is presented. +On the other hand, if +.B pmchart +is terminated while recording is in process, then the recording process +will prompt the user to choose immediate cessation of recording or for +it to continue on independently. +.PP +All of the record mode services available from +.B pmchart +are implemented with the assistance of the base Performance Co-Pilot +logging services \- refer to +.BR pmlogger (1) +and +.BR pmafm (1) +for an extensive description of the capabilities of these tools. +.SH CONFIGURATION FILE SYNTAX +.de ES +.ft CW +.nf +.in +0.5i +.. +.de EE +.ft R +.br +.in +.fi +.. +.PP +.B pmchart +loads predefined chart configurations (or "views") from external +files that conform to the following rules. In the descriptions below +keywords (shown in \f(CBbold\fP) may appear in upper, lower or +mixed case, elements shown in \f(CW[stuff]\fP are optional, and +user-supplied elements are shown as \f(CW<other stuff>\fP. +A vertical bar (|) is used where syntactic elements are alternatives. +Quotes (") +may be used to enclose lexical elements that may contain white space, +such as titles, labels and instance names. +.IP 1. 0.3i +The first line defines the configuration file type and should be +.ES +\f(CB#kmchart\fP +.EE +although +.B pmchart +provides backwards compatibility for the older +.B pmchart +view formats with an initial line of +.ES +\f(CB#pmchart\fP +.EE +.IP 2. 0.3i +After the first line, lines beginning with "#" as the first +non-white space character are treated as comments and skipped. +Similarly blank lines are skipped. +.IP 3. 0.3i +The next line should be +.ES +\f(CBversion\fP <n> <host-clause> +.EE +where \f(CW<n>\fP depends on the configuration file type, and +is \f(CB1\fP for \f(CBpmchart\fP else \f(CB1.1\fP, \f(CB1.2\fP or +\f(CB2.0\fP for \f(CBpmchart\fP. +.RS +The \f(CW<host-clause>\fP part is optional (and ignored) +for \fBpmchart\fP configuration +files, but required for the \fBpmchart\fP configuration files, and +is of the form +.ES +\f(CBhost\fP \f(CBliteral\fP +.EE +or +.ES +\f(CBhost\fP \f(CBdynamic\fP +.EE +.RE +.IP 4. 0.3i +A configuration contains one or more charts defined as follows: +.ES +\f(CBchart\fP [\f(CBtitle\fP <title>] \f(CBstyle\fP <style> <options> +.EE +If specified, the title will appear centred and above the graph area +of the chart. +The \f(CW<title>\fP is usually enclosed in quotes (") and if it +contains the sequence "%h" this will be replaced by the short form +of the hostname for the default source of metrics at the time +this chart was loaded. Alternatively, "%H" can be used to insert +the full host name. If the hostname appears to be an inet or IPv6 +address, no shortening will be attempted; it will be used as-is in +both replacement cases. +After the view is loaded, the title visibility and setting +can be manipulated using the +.I "Chart Title" +text box in the +.I "Edit\(->Chart" +dialog. +.RS +.PP +The \f(CW<style>\fP controls the initial plotting style of the chart, and +should be one of the keywords \f(CBplot\fP (line graph), \f(CBbar\fP, +\f(CBstacking\fP (stacked bar), +\f(CBarea\fP or \f(CButilization\fP. +After the view is loaded, the plotting style can be changed using the +.I "Edit\(->Chart" +Style dropdown list. +.PP +The \f(CW<options>\fP are zero or more of the optional elements: +.ES +[\f(CBscale\fP [from] <ymin> [to] <ymax>] [\f(CBlegend\fP <onoff>] +.EE +If \f(CBscale\fP is specfied, the vertical scaling is set for all plots +in the chart to a y-range defined by \f(CW<ymin>\fP and \f(CW<ymax>\fP. +Otherwise the +vertical axis will be autoscaled based on the values currently being +plotted. +.PP +\f(CW<onoff>\fP is one of the keywords \f(CBon\fP or \f(CBoff\fP and the +\f(CBlegend\fP clause controls the presence or absence of the plot +legend below the graph area. The default is for the legend to be shown. +After the view is loaded, the legend visibility +can be toggled using the +.I "Show Legend" +button in the +.I "Edit\(->Chart" +dialog. +.RE +.IP 5. 0.3i +.B pmchart +supports a \f(CBglobal\fP clause to specify the dimensions of the +top-level window (using the \f(CBwidth\fP and \f(CBheight\fP keywords), +the number of visible points (\f(CBpoints\fP keyword) and the starting +X and Y axis positions on the screen (\f(CBxpos\fP and \f(CBypos\fP +keywords). +Each of these \f(CBglobal\fP attributes takes an integer value as the +sole qualifier. +.IP 6. 0.3i +Each \f(CBchart\fP has one or more plots associated with it, as +defined by one of the following specifications: +.ES +\f(CBplot\fP + [\f(CBlegend\fP <title>] [\f(CBcolor\fP <colorspec>] [\f(CBhost\fP <hostspec>] + \f(CBmetric\fP <metricname> + [ \f(CBinstance\fP <inst> | \f(CBmatching\fP <pat> | \f(CBnot-matching\fP <pat> ] +.EE +.RS +.PP +The keyword \f(CBplot\fP may be replaced with the keyword +\f(CBoptional-plot\fP, in which case if the source of performance data +does not include the specified performance metric and/or instance, +then this plot is silently dropped from the chart. +.PP +If specified, the title will appear in the chart legend. +The \f(CW<title>\fP is usually enclosed in quotes (") and it may +contain one or more wildcard characters which will be expanded +using metric name, instance name, and host name for the plot. +The wildcards are "%i" (short unique instance name, up to the first +whitespace), "%I" (full instance name), "%h" (short host name, up +to the first dot), %H (full host name), "%m" (metric name shortened +to the final two PMNS components), and "%M" (full metric name). +.PP +For older +.B pmchart +configuration files, the keyword \f(CBtitle\fP must be used instead of +\f(CBlegend\fP. +Nowadays +.B pmchart +supports either keyword. +.PP +The \f(CBcolor\fP clause is optional for newer +.B pmchart +configuration files, but it was mandatory in the original +.B pmchart +configuration file format. +\f(CW<colorspec>\fP may be one of the following: +.ES +\f(CB#\-cycle\fP +\f(CBrgbi:\fPrr\f(CB:\fPgg\f(CB:\fPbb +\f(CB#\fPrgb +\f(CB#\fPrrggbb +\f(CB#\fPrrrgggbbb +\f(CB#\fPrrrrggggbbbb +<Xcolor> +.EE +where each of \f(CWr\fP, \f(CWg\fP and \f(CWb\fP are hexidecimal +digits (0-9 and A-F) representing respectively the red, green and +blue color components. +\f(CW<Xcolor>\fP is one of the color names from the X color database, +e.g. \f(CBred\fP or \f(CBsteelblue\fP, see also the output from +.BR showrgb (1). +.PP +The "color" \f(CB#\-cycle\fP specifies that +.B pmchart +should use the next in a pallet of colors that it uses cyclically +for each chart. This is the default if the \f(CBcolor\fP clause +is omitted. +.PP +The \f(CW<hostspec>\fP in the \f(CBhost\fP clause may be a hostname, +an IP address or an asterisk (*); the latter is used to mean the +default source of performance metrics. +For older +.B pmchart +configuration files, the \f(CBhost\fP clause must be present, for new +.B pmchart +configuration files it is optional, and if missing the default source +of performance metrics will be used. +.PP +The optional instance specification, +.IP (a) 0.3i +is omitted in which case one plot will be created for every instance of +the \f(CW<metricname>\fP metric +.IP (b) 0.3i +starts with \f(CBinstance\fP, in which case only the instance +named \f(CW<inst>\fP will be plotted +.IP (c) 0.3i +starts with \f(CBmatching\fP, in which case all instances whose +names match the pattern \f(CW<pat>\fP will be plotted; the pattern +uses extended regular expression notation in the style of +.BR egrep (1) +(refer to the PMCD view for an example) +.IP (d) 0.3i +starts with \f(CBnot-matching\fP, in which case all instances whose +names +.B do " " not +match the pattern \f(CW<pat>\fP will be plotted; the pattern +uses extended regular expression notation in the style of +.BR egrep (1) +(refer to the Netbytes view for an example) +.PP +.B pmchart +uses a bizarre syntactic notation where \f(CW<inst>\fP and +\f(CW<pat>\fP extend from the first non-white space character to the +end of the input line. For +.B pmchart +configuration files these elements are either delimited by white +space, or enclosed in quotes ("). +.RE +.IP 7. 0.3i +The optional \f(CBtab\fP directive can be used to create views with +multiple charts which span multiple Tabs. The syntax is as follows: +.ES +\f(CBtab\fP <label> [\f(CBhost\fP <host>] [\f(CBpoints\fP <points> [\f(CBsamples\fP <samples>]] +.EE +.RS +.ES +.PP +All chart specifications following this keyword will be created +on the new Tab, until the end of the configuration file or until +another \f(CBtab\fP keyword is encountered. +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.I /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (4). +.PP +Of particular note, the +.B $PCP_XCONFIRM_PROG +setting is explicitly and unconditionally overridden by +.B pmchart. +This is set to the +.BR pmconfirm (1), +utility, in order that some popup dialogs (particularly in the +area of Recording) maintain a consistent look-and-feel with the +rest of the +.B pmchart +application. +.SH SEE ALSO +.BR pmtime (1), +.BR pmconfirm (1), +.BR pmdumptext (1), +.BR PCPIntro (1), +.BR pmafm (1), +.BR pmval (1), +.BR pmcd (1), +.BR pminfo (1), +.BR pcp.conf (4), +.BR pcp.env (4) +and +.BR pmns (4). diff --git a/man/man1/pmclient.1 b/man/man1/pmclient.1 new file mode 100644 index 0000000..25d7d81 --- /dev/null +++ b/man/man1/pmclient.1 @@ -0,0 +1,182 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMCLIENT 1 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmclient\f1 \- a simple performance metrics client +.\" literals use .B or \f3 +.\" arguments use .I or \f2 +.SH SYNOPSIS +\f3pmclient\f1 +[\f3\-a\f1 \f2archive\f1] +[\f3\-h\f1 \f2host\f1] +[\f3\-n\f1 \f2pmnsfile\f1] +[\f3\-p\f1] +[\f3\-S\f1 \f2numsec\f1] +[\f3\-s\f1 \f2samples\f1] +[\f3\-t\f1 \f2interval\f1] +[\f3\-Z\f1 \f2timezone\f1] +[\f3\-z\f1] +.SH DESCRIPTION +.B pmclient +is a simple client that uses the Performance Metrics Application +Programming Interface (PMAPI) to report some high-level system +performance metrics. +.PP +The real value of +.B pmclient +is as a sample client using the +.BR PMAPI (3), +interfaces and to this end the source +code is included with +the Performance Co-Pilot (PCP) package (see +.BR PCPIntro (1)), +and is typically installed in +.IR /usr/share/pcp/demos/pmclient . +.PP +Normally +.B pmclient +operates on the distributed Performance Metrics Name Space (PMNS), +however if the +.B \-n +option is specified an alternative local PMNS is loaded from the file +.IR pmnsfile . +.PP +Unless directed to another host by the +.B \-h +option, or to an archive by the +.B \-a +option, +.B pmclient +will contact the Performance Metrics Collector Daemon (PMCD) +on the local host to obtain the required information. The +.B \-a +and +.B \-h +options are mutually exclusive. +.PP +By default, +.B pmclient +reports the time of day according to the local timezone on the +system where +.B pmclient +is run. +The +.B \-Z +option changes the timezone to +.I timezone +in the format of the environment variable +.B TZ +as described in +.BR environ (5). +The +.B \-z +option changes the timezone to the local timezone at the host that +is the source of the performance metrics, as identified via either the +.B \-h +or +.B \-a +options. +.PP +Other options control the specific information to be reported. +.TP +\f3\-p\f1 +The default behavior for replaying an archive, is to replay at +full speed. The +.B \-p +option may be used in conjunction with an archive, to request that +the prevailing real-time delay be applied between samples (see +.BR \-t ) +to effect a pause. +.TP +\f3\-S\f1 \f2numsec\f1 +The +.B \-S +option may be used in conjunction with an archive to request that +display start at the time +.I numsec +seconds from the start of the archive. +.TP +\f3\-s\f1 \f2samples\f1 +The argument +.I samples +defines the number of samples to be retrieved and reported. +If samples is 0 or +.B \-s +is not specified, +.B pmclient +will sample and report continuously (in real time mode) +or until the end of the PCP archive (in archive mode). +.TP +\f3\-t\f1 \f2interval\f1 +The default update \f2interval\f1 may be set to something other than the +default 5 seconds. +The +.I interval +argument follows the syntax described in +.BR PCPIntro (1), +and in the simplest form may be an unsigned integer (the implied +units in this case are seconds). +.PP +The output from +.B pmclient +is directed to standard output, and lists +.IP + 3 +Aggregate CPU utilization, in the range 0 to 1. +.IP + +If the system has more than 1 CPU, the ordinal +number of the busiest CPU, in the range 0 to ... +.IP + +If the system has more than 1 CPU, the CPU utilization for the busiest CPU. +.IP + +Real free memory in Mbytes. +.IP + +Aggregate physical disk I/O operations per second (IOPS). +.IP + +Load average over the last 1 minute and over the last 15 minutes. +.PP +.SH FILES +.PD 0 +.TP 10 +.B $PCP_DEMOS_DIR/pmclient +source code, documentation, configuration files and Makefile +when the PCP development package is installed +.PD +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.I /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). +.SH SEE ALSO +.BR PCPIntro (1), +.BR pmcd (1), +.BR pmchart (1), +.BR pmgenmap (1), +.BR pmstat (1), +.BR PMAPI (3), +.BR pcp.conf (5) +and +.BR pcp.env (5). +.SH DIAGNOSTICS +All are generated on standard error, and are intended to be self-explanatory. diff --git a/man/man1/pmcollectl.1 b/man/man1/pmcollectl.1 new file mode 100644 index 0000000..f6ce143 --- /dev/null +++ b/man/man1/pmcollectl.1 @@ -0,0 +1,332 @@ +'\"macro stdmacro +.\" +.\" Copyright 2012, Red Hat. +.\" Copyright 2003-2011, Hewlett-Packard Development Company, LP +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.TH PMCOLLECTL 1 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmcollectl\f1 \- collect data that describes the current system status +.SH SYNOPSIS +\f3pmcollectl\f1 +[\f3\-f\f1 \f2file\f1 | \f3\-p\f1 \f2file\f1 ...] +\f2[options\f1 ...] +.SH DESCRIPTION +.B pmcollectl +is a system-level performance monitoring utility that records or displays +specific operating system data for one or more sets of subsystems. +Any of the subsystems (such as CPU, Disks, Memory or Sockets) can be +included or excluded from data collection. +Data can either be displayed immediately to a terminal, or stored in files +for retrospective analysis. +.PP +.B pmcollectl +is a +.BR python (1) +script providing much of the functionality available from the +.BR collectl (1) +Linux utility (which happens to be written in +.BR perl (1)). +.PP +It makes use of the Performance Co-Pilot (PCP) toolkit to +simplify its implementation, as well as provide more of the +.B collectl +functionality on platforms other than Linux. +.PP +.B pmcollectl +has two primary modes of operation: +.IP 1. 0.3i +Record Mode (\f3\-f\f1 or \f3\-\-filename\f1 option) which reads data +from a live system and writes output to a file or displays it on a terminal. +.IP 2. 0.3i +Playback Mode (\f3\-p\f1 or \f3\-\-playback\f1 option) which reads data +from one or more PCP archive files and displays output on a terminal. +Note that these files are +.I not +raw +.B collectl +format data, rather they are archives created by the +.BR pmlogger (1) +utility (possibly indirectly, through use of the \f3\-f\f1 option to +.BR pmcollectl ). +.PP +.SH "RECORD MODE OPTIONS" +In this mode data is taken from a +.BR live +system and either displayed on the terminal or written to a PCP archive. +.PP +.B "\-h host" +.RS +Display metrics from +.I host +instead of displaying metrics from the local host. +.RE +.PP +.\" .B "--align" +.\" .RS +.\" .BR pmcollectl +.\" sample monitoring will be aligned such that a sample will always be taken at the +.\" top of a minute (this does NOT mean the first sample will occur then) so that all +.\" instances of +.\" .BR +.\" pmcollect +.\" running on any systems which have their clocks synchronized +.\" will all take samples at the same time. +.\" .RE +.\" +.\" .B "--all" +.\" .RS +.\" Collect summary data for ALL subsystems except slabs, since slab monitoring requires +.\" a different monitoring interval. +.\" You can use this switch anywhere \f3\-s\f1 can be used but not both together. +.\" .RE +.\" +.B "\-c, --count samples" +.RS +The number of samples to record. +.RE +.PP +.\" +.\" .B "\-D, --daemon" +.\" .RS +.\" Run +.\" .BR pmcollectl +.\" as a daemon, primarily used when starting as a service. +.\" This option sets the sampling interval to once every 10 seconds by default. +.\" .RE +.\" +.B "\-f, --filename filename" +.RS +This is the name of a PCP archive to write the output to. +.RE +.PP +.\" +.\" .B "\-F, --flush seconds" +.\" .RS +.\" Flush output buffers after this number of seconds. This is equivalent to +.\" issuing +.\" .B kill \-s USR1 +.\" to +.\" .B pmlogger +.\" at the same frequency (but a lot easier!). If 0, a flush will occur every +.\" data collection interval. +.\" .RE +.\" +.\" .B --home +.\" .RS +.\" Always start the display for the current interval at the top of the screen +.\" also known as the home position (non-plot format only). This generates a +.\" real-time, continuously refreshing display when the data fits on a single screen. +.\" .RE +.\" +.B "\-i, --interval interval" +.RS +This is the sampling interval in seconds. The default is 1 second. +.\" The default is 10 seconds when run as a daemon and 1 second otherwise. +.RE +.\" +.\" .B --nohup +.\" .RS +.\" Whenever collectl finishes a data collection interval, it checks to see if the starting parent +.\" has exited. This is to prevent the case in which someone might start a copy of collectl +.\" and then the process dies and collectl keeps running. If that is the behavior someone +.\" actually intends, they should start collectl with --nohup. +.\" +.\" NOTE - when running as a daemon, --nohup is implied. +.\" .RE +.\" +.B "\-R, --runtime duration" +.RS +Specify the duration of data collection where the duration is a number followed +by one of +.BR wdhms, +indicating how many weeks, days, hours, minutes or seconds +the collection is to be taken for. +.RE +.\" +.PP +.SH "PLAYBACK MODE OPTIONS" +In this mode, data is read from one or more PCP data files that were +generated with the recording option, or indirectly via the +.B pmlogger +utility. +.PP +.B "\-f, --filename filename" +.RS +If specified, this is the name of a PCP archive to write the output to (rather +than the terminal). +.RE +.PP +.\" .B "--from timerange" +.\" .RS +.\" Play back data starting with this time, which may optionally include the ending +.\" time as well, which is of the format of [date:]time[-[date:]time]. +.\" The leading 0 of the hour is optional and if the seconds field is not specified +.\" is assumed to be 0. If no dates specified the time(s) apply to each file specified +.\" by \-P. Otherwise the time(s) only apply to the first/last dates and any files +.\" between those dates will have all their data reported. +.\" .RE +.\" +.B "\-p, --playback filename" +.RS +Read data from the specified PCP archive files(s). +.RE +.PP +.\" .B "--thru time" +.\" .RS +.\" Time thru which to play back a raw file. See --from for more +.\" .RE +.SH "COMMON OPTIONS" +The following options are supported in both record and playback modes. +.PP +.B \--help +.RS +Display standard help message. +.RE +.PP +.\" +.\" .B --hr, --headerrepeat num +.\" .RS +.\" Sets the number of intervals to display data for before repeating the header. +.\" A value \-1 will prevent any headers from being displayed and a value of 0 +.\" will cause only a single header to be displayed and never repeated. +.\" .RE +.\" +.\" .B \-N, --nice +.\" .RS +.\" Set priority to a +.\" .BR nicer +.\" one of 10. +.RE +.B "\-s, --subsys subsystem" +.RS +This field controls which subsystem data is to be collected or played back +for. The rules for displaying results vary depending on the type of data to be +displayed. If you write data for CPUs and DISKs to a raw file and play it back +with \-sc, you will only see CPU data. If you play it back with \f3\-scm\f1 you +will still only see CPU data since memory data was not collected. +.\" However, when used with \f3\-P\f1, +.\" .B pmcollectl +.\" will always honor the subsystems specified with +.\" this switch so in the previous example you will see CPU +.\" data plus memory data of all 0s. +To see the current set of default subsystems, +which are a subset of this full list, +use \f3\-h\f1. +.PP +.\" You can also use + or \- to add or subtract subsystems to/from the default values. +.\" For example, "\-s\-cdn+N"< will remove cpu, disk and network monitoring from the +.\" defaults while adding network detail. +.PP +The default is "cdn", which stands for CPU, Disk and Network summary data. +.TP +.B "SUMMARY SUBSYSTEMS" +.PP +.\" .br +.\" b \- buddy info (memory fragmentation) +.br +c \- CPU +.br +d \- Disk +.br +f \- NFS V3 Data +.br +.\" i \- Inode and File System +.\" .br +j \- Interrupts +.br +.\" l \- Lustre +.\" .br +m \- Memory +.br +n \- Networks +.br +.\" s \- Sockets +.\" .br +.\" t \- TCP +.\" .br +.\" x \- Interconnect +.br +y \- Slabs (system object caches) +.RS +.RE +.PP +.TP +.B "DETAIL SUBSYSTEMS" +.PP +This is the set of +.BR detail +data from which in most cases the corresponding summary data is +derived. +So, if one has 3 disks and chooses +.B \-sd, +one will only see a single total taken +across all 3 disks. If one +chooses +.B \-sD, +individual disk totals will be reported but no totals. +.\" Choosing .B \-sdD will get you both. +.PP +.br +C \- CPU +.br +D \- Disk +.br +F \- NFS Data +.br +J \- Interrupts +.br +.\" L \- Lustre OST detail OR client Filesystem detail +.\" .br +M \- Memory node data, which is also known as NUMA data +.br +N \- Networks +.br +.\" T \- 65 TCP counters only available in plot format +.\" .br +.\" X \- Interconnect +.br +Y \- Slabs (system object caches) +.br +Z \- Processes +.RE +.PP +.\" .B \-w +.\" .RS +.\" Disply data in +.\" .BR wide +.\" mode. When displaying data on the terminal, some data is formatted followed +.\" by a K, M or G as appropriate. Selecting this switch will cause the +.\" full field to be displayed. Note that there is no attempt +.\" to align data with the column headings in this mode. +.\" .RE +.PD +.B --verbose +.RS +Display output in verbose mode. This often displays more data than in the default mode. When +displaying detail data, verbose mode is forced. Furthermore, if summary data for a single +subsystem is to be displayed in verbose mode, the headers are only repeated occasionally whereas +if multiple subsystems are involved each needs their own header. +.RE +.PP +.SH "SEE ALSO" +.BR PCPIntro (1), +.BR collectl (1), +.BR perl (1), +.BR python (1), +.BR pmlogger (1), +.BR pmcd (1), +.BR pmprobe (1), +.BR pmval (1), +.BR PMAPI (3), +and +.BR pcp.conf (5). diff --git a/man/man1/pmconfig.1 b/man/man1/pmconfig.1 new file mode 100644 index 0000000..6c82aea --- /dev/null +++ b/man/man1/pmconfig.1 @@ -0,0 +1,70 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2012,2014 Red Hat. +.\" Copyright (c) 2009 Aconex. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.TH PMCONFIG 1 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmconfig\f1 \- Performance Co-Pilot configuration parameters +.SH SYNOPSIS +\f3$PCP_BINADM_DIR/pmconfig\f1 +[\f3\-a\f1|\f3-l\f1] +[\f3\-L\f1] +[\f3\-s\f1] +[\f2name ...\f1] +.SH DESCRIPTION +.B pmconfig +displays the values for some or all configuration parameters +of the local Performance Co-Pilot toolkit installation. +.PP +The +.B \-L +option may be used to change the default reporting mode so that +the capabilities of the PCP library are reported, rather than the +PCP environment. +.PP +An output format suitable for sourcing in shell scripts can be +obtained using the +.B \-s +option, which ensures configuration information is quoted and +preceded by an export statement. +When not reporting the library capabilities, this mode will +produce a statement that does not override an existing setting +in the environment for PCP configuration variables. +.PP +In the default operating mode, +.B pmconfig +is often used in conjunction with the +.B $PCP_DIR +environment variable to setup scripts running under the Windows +operating system, where the filesystem hierarchy differs greatly +to the of Linux/UNIX-based operating systems. +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.I /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). +.SH SEE ALSO +.BR pmGetConfig (3), +.BR pcp.conf (5) +and +.BR pcp.env (5). diff --git a/man/man1/pmcpp.1 b/man/man1/pmcpp.1 new file mode 100644 index 0000000..26a2305 --- /dev/null +++ b/man/man1/pmcpp.1 @@ -0,0 +1,197 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2011 Ken McDonell. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMCPP 1 "" "Performance Co-Pilot" +.SH NAME +\f3pmcpp\f1 \- simple preprocessor for the Performance Co-Pilot +.\" literals use .B or \f3 +.\" arguments use .I or \f2 +.SH SYNOPSIS +.B pmcpp +[\f3\-D\f1 \f2name\f1[=\f2value\f1] ...] +[\f2infile\f1] +.SH DESCRIPTION +.B pmcpp +provides a very simple pre-processor for manipulating Performance +Metric Name Space (PMNS) files for the +Performance Co-Pilot (PCP). It is most commonly used internally +to process the PMNS file(s) after +.BR pmLoadNameSpace (3) +or +.BR pmLoadASCIINameSpace (3) +is called. +.PP +Input lines are read from +.I infile +(or standard input if +.I infile +is not specified), processed and written to standard output. +.PP +All C-style comments of the form /* ... */ are stripped from the +input stream. +.PP +There are no predefined macros for +.B pmcpp +although macros may be defined on the command line using the +.B \-D +option, where +.I name +and +.I value +must follow the same rules as described below for the +.B #define +directive. +.PP +.B pmcpp +accepts the following directives in the input stream (like +.BR cpp (1)): +.IP * 3n +\fB#include "\fIfilename\fB"\fR +.br +or +.br +\fB#include <\fIfilename\fB>\fR +.br +In either case the directory search path for +.I filename +tries +.I filename +first, then the directory for the command line +.I infile +(if any), +followed by the +.B $PCP_VAR_DIR/pmns +directory. +.B #include +directives may be nested, up to a maximum depth of 5. +.IP * 3n +\fB#define \fIname value\fR +.br +Defines a value for the macro +.I name +which must be a valid C-style name, so leading alphabetic or ``_'' followed by +zero or more alphanumerics or ``_''. +.I value +is optional (and defaults to an empty value) but when present it may +.B not +contain white space and quoting or escaping is +.B not +supported. +.IP * 3n +\fB#undef \fIname\fR +.br +Removes the macro definition, if any, for +.IR name . +.IP * 3n +\fB#ifdef \fIname\fR +.br +\&... +.br +\fB#endif\fR +.br +or +.br +\fB#ifndef \fIname\fR +.br +\&... +.br +\fB#endif\fR +.br +The enclosing lines will be stripped or included, depending if the +macro +.I name +is defined or not. +.PP +Macro substitution is achieved by breaking the input stream into words +separated by white space or one of the characters ``.'' or ``:'' +\- this matches the syntax of the PMNS, see +.BR pmns (5). +Each word is checked and if it matches a macro name, the word is +replaced by the macro value, otherwise the word is unchanged. +.PP +There is generally one output line for each input line, although the line +may be empty if the text has been stripped due to the handling of +comments or conditional directives. When there is a change in the input +stream, an additional output line is generated of the form: +.PP +.ti +10n +# line "name" +.PP +to indicate the +.I following +line of output corresponds to line number +.I line +of the input file +.IR name . +.PP +Important +.BR cpp (1) +features that are +.B not +supported by +.B pmcpp +include: +.IP * 3n +\fB#if \fIexpr\fR +.br +\&... +.br +\fB#endif\fR +.IP * 3n +Nested use of +.B #ifdef +or +.BR #ifndef . +.IP * 3n +.B #else +within an +.B #ifdef +or +.BR #ifndef . +.IP * 3n +Stripping C++ style comments, as in // comment +.IP * 3n +Error recovery - the first error encountered by +.B pmcpp +will be fatal. +.IP * 3n +.BR cpp (1) +command line options like +.B \-U , +.B \-P +and +.BR \-I . +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.I /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). +.SH SEE ALSO +.BR cpp (1), +.BR pmLoadASCIINameSpace (3), +.BR pmLoadNameSpace (3), +.BR pmns (5), +.BR pcp.conf (5) +and +.BR pcp.env (5). diff --git a/man/man1/pmdaapache.1 b/man/man1/pmdaapache.1 new file mode 100644 index 0000000..6b489d1 --- /dev/null +++ b/man/man1/pmdaapache.1 @@ -0,0 +1,176 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2014 Red Hat. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.TH PMDAAPACHE 1 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmdaapache\f1 \- Apache2 web server performance metrics domain agent (PMDA) +.SH SYNOPSIS +\f3$PCP_PMDAS_DIR/apache/pmdaapache\f1 +[\f3\-d\f1 \f2domain\f1] +[\f3\-l\f1 \f2logfile\f1] +[\f3\-U\f1 \f2username\f1] +[\f3\-S\f1 \f2server\f1] +[\f3\-P\f1 \f2port\f1] +[\f3\-L\f1 \f2location\f1] +.SH DESCRIPTION +.B pmdaapache +is a Performance Metrics Domain Agent (PMDA) which extracts +performance metrics describing the state of an Apache web server. +.PP +The +.B apache +PMDA exports metrics that measure the request rate, cumulative +request sizes, uptime and various connection states for active +clients. +.PP +This information is obtained by performing a HTTP request to the +server status URL, which must be enabled in the +.I httpd.conf +configuration file. +.P +.ft CW +.nf +.in +0.5i +ExtendedStatus on +<Location /server-status> +SetHandler server-status +Order deny,allow +Deny from all +Allow from localhost +</Location> +.in +.fi +.ft 1 +.PP +A brief description of the +.B pmdaapache +command line options follows: +.TP 5 +.B \-d +It is absolutely crucial that the performance metrics +.I domain +number specified here is unique and consistent. +That is, +.I domain +should be different for every PMDA on the one host, and the same +.I domain +number should be used for the same PMDA on all hosts. +.TP +.B \-l +Location of the log file. By default, a log file named +.I apache.log +is written in the current directory of +.BR pmcd (1) +when +.B pmdaapache +is started, i.e. +.B $PCP_LOG_DIR/pmcd . +If the log file cannot +be created or is not writable, output is written to the standard error instead. +.TP +.B \-S +Query the Apache status information from the named +.I server +rather than the local host. +.TP +.B \-P +Query the Apache status information from the given +.I port +rather than the default (80). +.TP +.B \-L +Specify an alternative +.I location +for finding the server-status page. +.TP +.B \-U +User account under which to run the agent. +The default is the unprivileged "pcp" account in current versions of PCP, +but in older versions the superuser account ("root") was used by default. +.SH INSTALLATION +If you want access to the names, help text and values for the apache +performance metrics, do the following as root: +.PP +.ft CW +.nf +.in +0.5i +# cd $PCP_PMDAS_DIR/apache +# ./Install +.in +.fi +.ft 1 +.PP +If you want to undo the installation, do the following as root: +.PP +.ft CW +.nf +.in +0.5i +# cd $PCP_PMDAS_DIR/apache +# ./Remove +.in +.fi +.ft 1 +.PP +.B pmdaapache +is launched by +.BR pmcd (1) +and should never be executed directly. +The Install and Remove scripts notify +.BR pmcd (1) +when the agent is installed or removed. +.SH FILES +.PD 0 +.TP 10 +.B $PCP_PMCDCONF_PATH +command line options used to launch +.B pmdaapache +.TP 10 +.B $PCP_PMDAS_DIR/apache/help +default help text file for the apache metrics +.TP 10 +.B $PCP_PMDAS_DIR/apache/Install +installation script for the +.B pmdaapache +agent +.TP 10 +.B $PCP_PMDAS_DIR/apache/Remove +undo installation script for the +.B pmdaapache +agent +.TP 10 +.B $PCP_LOG_DIR/pmcd/apache.log +default log file for error messages and other information from +.B pmdaapache +.PD +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.I /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). +.SH SEE ALSO +.BR PCPIntro (1), +.BR httpd (8), +.BR pmcd (1), +.BR pcp.conf (5) +and +.BR pcp.env (5). diff --git a/man/man1/pmdabash.1 b/man/man1/pmdabash.1 new file mode 100644 index 0000000..05a4faf --- /dev/null +++ b/man/man1/pmdabash.1 @@ -0,0 +1,250 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2012 Red Hat. +.\" Copyright (c) 2012 Nathan Scott. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMDABASH 1 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmdabash\f1 \- Bourne-Again SHell trace performance metrics domain agent +.SH SYNOPSIS +\f3$PCP_PMDAS_DIR/bash/pmdabash\f1 +[\f3\-C\f1] +[\f3\-d\f1 \f2domain\f1] +[\f3\-l\f1 \f2logfile\f1] +[\f3\-I\f1 \f2interval\f1] +[\f3\-t\f1 \f2timeout\f1] +[\f3\-U\f1 \f2username\f1] +\f2configfile\f1 +.br +.SH DESCRIPTION +.B pmdabash +is an experimental Performance Metrics Domain Agent (PMDA) which +exports "xtrace" events from a traced +.BR bash (1) +process. +This includes the command execution information that would +usually be sent to standard error with the +.BR "set -x" +option to the shell. +.PP +Event metrics are exported showing each command executed, the +function name and line number in the script, and a timestamp. +Additionally, the process identifier for the shell and its parent +process are exported. +.PP +This requires +.B bash +version 4 or later. +.PP +A brief description of the +.B pmdabash +command line options follows: +.TP 5 +.B \-d +It is absolutely crucial that the performance metrics +.I domain +number specified here is unique and consistent. +That is, +.I domain +should be different for every PMDA on the one host, and the same +.I domain +number should be used for the same PMDA on all hosts. +.TP 5 +.B \-l +Location of the log file. By default, a log file named +.I bash.log +is written in the current directory of +.BR pmcd (1) +when +.B pmdabash +is started, i.e. +.BR $PCP_LOG_DIR/pmcd . +If the log file cannot +be created or is not writable, output is written to the standard error instead. +.TP 5 +.B \-s +Amount of time (in seconds) between subsequent evaluations of the shell +trace file descriptor(s). +The default is 2 seconds. +.PP +.TP 5 +.B \-m +Maximum amount of memory to be allowed for each event queue (one per traced process). +The default is 2 megabytes. +.TP 5 +.B \-U +User account under which to run the agent. +The default is the unprivileged "pcp" account in current versions of PCP, +but in older versions the superuser account ("root") was used by default. +.PP +.SH INSTALLATION +In order for a host to export the names, help text and values for the bash +performance metrics, do the following as root: +.PP +.ft CW +.nf +.in +0.5i +# cd $PCP_PMDAS_DIR/bash +# ./Install +.in +.fi +.ft 1 +.PP +As soon as an instrumented shell script (see INSTRUMENTATION selection below) is +run, with tracing enabled, new metric values will appear - no further setup of the +agent is required. +.PP +If you want to undo the installation, do the following as root: +.PP +.ft CW +.nf +.in +0.5i +# cd $PCP_PMDAS_DIR/bash +# ./Remove +.in +.fi +.ft 1 +.PP +.B pmdabash +is launched by +.BR pmcd (1) +and should never be executed directly. +The Install and Remove scripts notify +.BR pmcd (1) +when the agent is installed or removed. +.SH INSTRUMENTATION +In order to allow the flow of event data between a +.BR bash (1) +script and +.BR pmdabash , +the script should take the following actions: +.PP +.ft CW +.nf +.in +0.5i +#!/bin/sh +source $PCP_DIR/etc/pcp.sh + +pcp_trace on $@ # enable tracing +echo "awoke, $count" + +pcp_trace off # disable tracing +.in +.fi +.ft 1 +.PP +The tracing can be enabled and disabled any number of times by the script. +On successful installation of the agent, several metrics will be available: +.PP +.ft CW +.nf +.in +0.5i +$ pminfo bash +bash.xtrace.numclients +bash.xtrace.maxmem +bash.xtrace.queuemem +bash.xtrace.count +bash.xtrace.records +bash.xtrace.parameters.pid +bash.xtrace.parameters.parent +bash.xtrace.parameters.lineno +bash.xtrace.parameters.function +bash.xtrace.parameters.command +.in +.fi +.ft 1 +.PP +When an instrumented script is running, the generation of event records +can be verified using the +.BR pmevent (1) +command, as follows: +.PP +.ft CW +.nf +.in +0.5i +$ pmevent \-t 1 \-x '' bash.xtrace.records +host: localhost +samples: all +bash.xtrace.records["4538 ./test-trace.sh 1 2 3"]: 5 event records + 10:00:05.000 --- event record [0] flags 0x19 (point,id,parent) --- + bash.xtrace.parameters.pid 4538 + bash.xtrace.parameters.parent 4432 + bash.xtrace.parameters.lineno 43 + bash.xtrace.parameters.command "true" + 10:00:05.000 --- event record [1] flags 0x19 (point,id,parent) --- + bash.xtrace.parameters.pid 4538 + bash.xtrace.parameters.parent 4432 + bash.xtrace.parameters.lineno 45 + bash.xtrace.parameters.command "(( count++ ))" + 10:00:05.000 --- event record [2] flags 0x19 (point,id,parent) --- + bash.xtrace.parameters.pid 4538 + bash.xtrace.parameters.parent 4432 + bash.xtrace.parameters.lineno 46 + bash.xtrace.parameters.command "echo 'awoke, 3'" + 10:00:05.000 --- event record [3] flags 0x19 (point,id,parent) --- + bash.xtrace.parameters.pid 4538 + bash.xtrace.parameters.parent 4432 + bash.xtrace.parameters.lineno 47 + bash.xtrace.parameters.command "tired 2" + 10:00:05.000 --- event record [4] flags 0x19 (point,id,parent) --- + bash.xtrace.parameters.pid 4538 + bash.xtrace.parameters.parent 4432 + bash.xtrace.parameters.lineno 38 + bash.xtrace.parameters.function "tired" + bash.xtrace.parameters.command "sleep 2" +.in +.fi +.ft 1 +.SH FILES +.PD 0 +.TP 10 +.B $PCP_PMCDCONF_PATH +command line options used to launch +.B pmdabash +.TP 10 +.B $PCP_PMDAS_DIR/bash/help +default help text file for the bash metrics +.TP 10 +.B $PCP_PMDAS_DIR/bash/Install +installation script for the +.B pmdabash +agent +.TP 10 +.B $PCP_PMDAS_DIR/bash/Remove +undo installation script for +.B pmdabash +.TP 10 +.B $PCP_LOG_DIR/pmcd/bash.log +default log file for error messages and other information from +.B pmdabash +.PD +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.B /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). +.SH SEE ALSO +.BR bash (1), +.BR pmevent (1) +and +.BR pmcd (1). diff --git a/man/man1/pmdacisco.1 b/man/man1/pmdacisco.1 new file mode 100644 index 0000000..407d042 --- /dev/null +++ b/man/man1/pmdacisco.1 @@ -0,0 +1,345 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2012 Red Hat. +.\" Copyright (c) 2000-2002 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMDACISCO 1 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmdacisco\f1 \- Cisco router performance metrics domain agent (PMDA) +.SH SYNOPSIS +\f3$PCP_PMDAS_DIR/cisco/pmdacisco\f1 +[\f3\-d\f1 \f2domain\f1] +[\f3\-l\f1 \f2logfile\f1] +[\f3\-U\f1 \f2username\f1] +[\f3\-P\f1 \f2password\f1] +[\f3\-r\f1 \f2refresh\f1] +[\f3\-s\f1 \f2prompt\f1] +[\f3\-M\f1 \f2username\f1] +[\f3\-x\f1 \f2port\f1] +\f2host:interface-spec\f1 [...] +.br +\f3$PCP_PMDAS_DIR/cisco/parse\f1 +[options] +\f2host:interface-spec\f1 [...] +.br +\f3$PCP_PMDAS_DIR/cisco/probe\f1 +[\f3\-P\f1 \f2password\f1] +[\f3\-s\f1 \f2prompt\f1] +[\f3\-U\f1 \f2username\f1] +[\f3\-x\f1 \f2port\f1] +\f2host\f1 +.SH DESCRIPTION +.B pmdacisco +is a Performance Metrics Domain Agent (PMDA) which extracts +performance metrics from one or more Cisco routers. +.PP +A brief description of the +.B pmdacisco +command line options follows: +.TP 5 +.B \-d +It is absolutely crucial that the performance metrics +.I domain +number specified here is unique and consistent. +That is, +.I domain +should be different for every PMDA on the one host, and the same +.I domain +number should be used for the same PMDA on all hosts. +.TP 5 +.B \-l +Location of the log file. By default, a log file named +.I cisco.log +is written in the current directory of +.BR pmcd (1) +when +.B pmdacisco +is started, i.e. +.IR $PCP_LOG_DIR/pmcd . +If the log file cannot +be created or is not writable, output is written to the standard error instead. +.TP 5 +.B \-P +By default, it is assumed that no user-level password is +required to access the Cisco's telnet port. If user-level passwords +have been enabled on the Ciscos, then those passwords must +be specified to +.BR pmdacisco . +If specified with the +.B \-P +option, +.I password +will be used as the default user-level password for all +Ciscos. See also the INTERFACE IDENTIFICATION section below. +.TP 5 +.B \-r +.B pmdacisco +will refresh the current values for all performance metrics by +contacting each Cisco router once every +.I refresh +seconds. +The default +.I refresh +is 120 seconds. +.TP 5 +.B \-s +The Cisco command prompt ends with the string +.IR prompt . +The default value is ``>''. +The only way +.B pmdacisco +can synchronize the sending of commands and the parsing of output is by +recognizing +.I prompt +as a unique string that comes at the end of all output, i.e. as the +command prompt when waiting for the next command. +.TP 5 +.B \-U +By default, it is assumed that no username login is +required to access the Cisco's telnet port. If username login +has been enabled on the Ciscos, then the corresponding usernames must +be specified to +.BR pmdacisco . +If specified with the +.B \-U +option, +.I username +will be used as the default username login for all +Ciscos. See also the INTERFACE IDENTIFICATION section below. +.TP 5 +.B \-M +User account under which to run the agent. +The default is the unprivileged "pcp" account in current versions of PCP, +but in older versions the superuser account ("root") was used by default. +.TP 5 +.B \-x +Connect to the Cisco via TCP port number +.I port +rather than the default 23 for a telnet connection. +.PP +For each interface, once the telnet connection +is established, +.B pmdacisco +is willing to wait up to 5 seconds +for the Cisco to provide a new snapshot +of the requested information. If this does +not happen, the telnet connection is broken and no values are +returned. This prevents +.B pmdacisco +tying up the Cisco's telnet +ports waiting indefinitely when the response from the +router is not what is expected, e.g. if the format of the ``show int'' output +changes, or the command is in error because an +interface is no longer configured on the router. +.SH INTERFACE IDENTIFICATION +As each Cisco router can support multiple network interfaces +and/or multiple communications protocols, it is necessary to +tell +.B pmdacisco +which interfaces are to be monitored. +.PP +The +.I host:interface-spec +arguments on the command line define a particular interface +on a particular Cisco router. +.I host +should be a hostname or a ``dot-notation'' IP address +that identifies the telnet port of a particular Cisco router. +There are several components of the +.I interface-spec +as follows. +.TP +protocol +One of the abbreviations +.BR a , +.BR B , +.BR E , +.BR e , +.BR f , +.BR G , +.BR h , +.B s +or +.B Vl +respectively for ATM, BRI (ISDN), FastEthernet, Ethernet, FDDI, GigabitEthernet, +HSSI, serial or Vlan. +.TP +interface +Depending on the model of the Cisco, this will either +be an integer, e.g.\& +.BR s0 , +or an integer followed by a slash (``/'') followed by a subinterface +identification in one of a variety of syntactic forms, e.g.\& +.BR e1/0 , +.B G0/0/1 +or +.BR s4/2.1 . +.RS +.P +To discover the valid interfaces on a particular Cisco, +connect to the telnet port (using +.BR telnet (1)) +and enter the command "show int" and look for the interface +identifiers following the keywords ``Ethernet'', ``Fddi'', ``Serial'', etc. +.P +Alternatively run the +.BR probe +command. +.RE +.TP +username +If there is a username login, and it is different to the +default (see +.B \-U +above), it may be optionally specified here by appending +\&``@'' and the username to the end of +.IR interface-spec . +.TP +password +If there is a user-level password, and it is different to the +default (see +.B \-P +above), it may be optionally specified here by appending +a question mark (``?'') and the password to the end of +.IR interface-spec . +.TP +prompt +If the Cisco command prompt is different to the +default (see +.B \-s +above), it may be optionally specified here by appending +an exclamation mark (``!'') and the prompt to the end of +.IR interface-spec . +.PP +The following are examples of valid +.I interface-spec +arguments. +.in +1i +.nf +my-router:e1/2 +123.456.789.0:s0 +wancisco:f2/3?trust_me +somecisco:G1/0!myprompt +cisco34.foo.bar.com:e2?way2cool +mycisco:s2/2.1@mylogin +yourcisco:E0/0@yourlogin?yourpassword +mycisco:E0/0@mylogin?mypassword!myprompt +.fi +.in +.SH HELPER UTILITIES +The +.B probe +command may be used to discover the names of all interfaces for +a particular Cisco router identified by +.IR host . +The +.BR \-P +argument is the same as for +.BR pmdacisco . +.PP +The +.B parse +command takes exactly the same arguments as +.BR pmdacisco , +but executes outside the control of any +.BR pmcd (1) +and so may be used to diagnose problems with handling a particular +Cisco router and/or one of its interfaces. +.PP +Additional diagnostic verbosity may be produced using the +.B "\-D appl0,appl1,appl2" +command line option. +.B appl0 +logs connect and disconnect events, login progress, high-level +flow of control and extracted statistics. +.B appl1 +traces all commands sent to the Cisco device. +.B appl2 +logs tokenizing and parsing of the output from the Cisco device. +Diagnostics are generated on standard error as each sample is fetched +and parsed. +.SH INSTALLATION +If you want access to the names, help text and values for the Cisco +performance metrics, do the following as root: +.PP +.ft CW +.nf +.in +0.5i +# cd $PCP_PMDAS_DIR/cisco +# ./Install +.in +.fi +.ft 1 +.PP +If you want to undo the installation, do the following as root: +.PP +.ft CW +.nf +.in +0.5i +# cd $PCP_PMDAS_DIR/cisco +# ./Remove +.in +.fi +.ft 1 +.PP +.B pmdacisco +is launched by +.BR pmcd (1) +and should never be executed directly. +The Install and Remove scripts notify +.BR pmcd (1) +when the agent is installed or removed. +.SH FILES +.PD 0 +.TP 10 +.B $PCP_PMCDCONF_PATH +command line options used to launch +.B pmdacisco +.TP 10 +.B $PCP_PMDAS_DIR/cisco/help +default help text file for the Cisco metrics +.TP 10 +.B $PCP_PMDAS_DIR/cisco/Install +installation script for the +.B pmdacisco +agent +.TP 10 +.B $PCP_PMDAS_DIR/cisco/Remove +undo installation script for the +.B pmdacisco +agent +.TP 10 +.B $PCP_LOG_DIR/pmcd/cisco.log +default log file for error messages and other information from +.B pmdacisco +.PD +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.I /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). +.SH SEE ALSO +.BR pmcd (1), +.BR pcp.conf (5) +and +.BR pcp.env (5). diff --git a/man/man1/pmdadmcache.1 b/man/man1/pmdadmcache.1 new file mode 100644 index 0000000..2fba936 --- /dev/null +++ b/man/man1/pmdadmcache.1 @@ -0,0 +1,64 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2014 Red Hat. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMDADMCACHE 1 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmdadmcache\f1 \- Device Mapper Cache PMDA +.SH DESCRIPTION +\f3pmdadmcache\f1 is a Performance Metrics Domain Agent (PMDA) which exports +metric values about device mapper cache target devices, made available by the +.B dm-cache +Linux kernel module. +.PP +The device mapper cache target aims to improve the performance of a block +device (such as a spindle) by dynamically migrating some of its data to a +faster, smaller device (such as a Solid State Drive). +.PP +This PMDA exports metrics for each configured cache, including sizes, +cache read and write hits and misses, rates of cached block demotion +and promotion, and the mode each cache is operating in. +.SH INSTALLATION +Install the dmcache PMDA by using the Install script as root: +.PP + # cd $PCP_PMDAS_DIR/dmcache +.br + # ./Install +.PP +To uninstall, do the following as root: +.PP + # cd $PCP_PMDAS_DIR/dmcache +.br + # ./Remove +.PP +\fBpmdadmcache\fR is launched by \fIpmcd\fR(1) and should never be executed +directly. The Install and Remove scripts notify \fIpmcd\fR(1) when the +agent is installed or removed. +.SH FILES +.IP "\fB$PCP_PMDAS_DIR/dmcache/Install\fR" 4 +installation script for the \fBpmdadmcache\fR agent +.IP "\fB$PCP_PMDAS_DIR/dmcache/Remove\fR" 4 +undo installation script for the \fBpmdadmcache\fR agent +.IP "\fB$PCP_LOG_DIR/pmcd/dmcache.log\fR" 4 +default log file for error messages from \fBpmdadmcache\fR +.SH PCP ENVIRONMENT +Environment variables with the prefix \fBPCP_\fR are used to parameterize +the file and directory names used by \fBPCP\fR. On each installation, the +file \fB/etc/pcp.conf\fR contains the local values for these variables. +The \fB$PCP_CONF\fR variable may be used to specify an alternative +configuration file, as described in \fIpcp.conf\fR(5). +.SH SEE ALSO +.BR pmcd (1) +and +.BR PCPIntro (1). diff --git a/man/man1/pmdagfs2.1 b/man/man1/pmdagfs2.1 new file mode 100644 index 0000000..5e4e328 --- /dev/null +++ b/man/man1/pmdagfs2.1 @@ -0,0 +1,86 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2013 Red Hat. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMDAGFS2 1 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmdagfs2\f1 \- Global Filesystem v2 (GFS2) PMDA +.SH DESCRIPTION +.B pmdagfs2 +is a Performance Metrics Domain Agent (PMDA) which exports +metric values about mounted GFS2 filesystems from the debugfs filesystem. +This PMDA requires debugfs along with at least one mounted GFS2 filesystem +to be mounted in order to be able to provide metric data. +.PP +This PMDA can be used with GFS2 filesystems which are both mounted as +local filesystems and filesystems which are mounted as shared storage +within a clustered environment. However there are some metrics which +specifically require GFS2 to be setup in a clustered environment to be +able to provide metric data. This is due to them expecting locking +messages to be passed via the distributed lock manager (DLM) between nodes +of a cluster in order to generate their output. +.PP +These cluster-environment-only metrics can be distinguished by the +inclusion of their corresponding control metrics so that they can be +optionally enabled or disabled on systems where they are not desired to be +monitored or not supported. +.PP +.BR pmstore (3) +can be used to assign values to these control metrics in order to enable (1) +or disable (0) them. +This mechanism is also useful on distributions that do not currently +have full support for the GFS2 trace-points or provide older versions of +the GFS2 driver. +.PP +Further details on clustering and GFS2 can be found at http://redhat.com +.SH INSTALLATION +Install the GFS2 PMDA by using the Install script as root: +.PP + # cd $PCP_PMDAS_DIR/gfs2 +.br + # ./Install +.PP +To uninstall, do the following as root: +.PP + # cd $PCP_PMDAS_DIR/gfs2 +.br + # ./Remove +.PP +.B pmdagfs2 +is launched by +.BR pmcd (1) +and should never be executed directly. +The Install and Remove scripts notify +.B pmcd +when the agent is installed or removed. +.SH FILES +.IP "\fB$PCP_PMDAS_DIR/gfs2/help\fR" 4 +default help text file for the GFS2 metrics +.IP "\fB$PCP_PMDAS_DIR/gfs2/Install\fR" 4 +installation script for the \fBpmdagfs2\fR agent +.IP "\fB$PCP_PMDAS_DIR/gfs2/Remove\fR" 4 +undo installation script for the \fBpmdagfs2\fR agent +.IP "\fB$PCP_LOG_DIR/pmcd/gfs2.log\fR" 4 +default log file for error messages from \fBpmdagfs2\fR +.SH PCP ENVIRONMENT +Environment variables with the prefix \fBPCP_\fR are used to parameterize +the file and directory names used by \fBPCP\fR. On each installation, the +file \fB/etc/pcp.conf\fR contains the local values for these variables. +The \fB$PCP_CONF\fR variable may be used to specify an alternative +configuration file, as described in \fIpcp.conf\fR(5). +.SH SEE ALSO +.BR pmcd (1), +.BR pmstore (1), +and +.BR gfs2 (5). diff --git a/man/man1/pmdagluster.1 b/man/man1/pmdagluster.1 new file mode 100644 index 0000000..6c7109e --- /dev/null +++ b/man/man1/pmdagluster.1 @@ -0,0 +1,89 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2013 Red Hat. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMDAGLUSTER 1 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmdagluster\f1 \- Gluster Filesystem PMDA +.SH DESCRIPTION +\f3pmdagluster\f1 is a Performance Metrics Domain Agent (PMDA) which exports +metric values about mounted gluster filesystems using the +.BR gluster (8) +command. +This PMDA exports metrics about volumes and bricks both local and remote to +the node where pmdagluster is running. +.PP +The gluster filesystem supports fine-grained control over enabling statistics +on individual volumes, so that the values are optionally enabled or disabled +on systems where they are not desired to be monitored. +.PP +The +.BR pmstore (1) +command can be used to enable and disable profiling of volumes. +Using the individual instances of the gluster.volume.profile metric, +one can set their values (and associated profiling) either on (1) or off (0). +Additionally, +.BR pminfo (1) +can report on the current status of profiling of each volume. +.P +.ft CW +.nf +.in +0.5i +# pminfo \(hyf gluster.volume.profile + +gluster.volume.profile + inst [0 or "gv0"] value 0 + inst [1 or "gv1"] value 1 + +# pmstore \(hyi "gv0" gluster.volume.profile 1 +gluster.volume.profile inst [0 or "gv0"] old value=0 new value=1 +.in +.fi +.PP +Further details on the gluster filesystem can be found at http://www.gluster.org +.SH INSTALLATION +Install the gluster PMDA by using the Install script as root: +.PP + # cd $PCP_PMDAS_DIR/gluster +.br + # ./Install +.PP +To uninstall, do the following as root: +.PP + # cd $PCP_PMDAS_DIR/gluster +.br + # ./Remove +.PP +\fBpmdagluster\fR is launched by \fIpmcd\fR(1) and should never be executed +directly. The Install and Remove scripts notify \fIpmcd\fR(1) when the +agent is installed or removed. +.SH FILES +.IP "\fB$PCP_PMDAS_DIR/gluster/Install\fR" 4 +installation script for the \fBpmdagluster\fR agent +.IP "\fB$PCP_PMDAS_DIR/gluster/Remove\fR" 4 +undo installation script for the \fBpmdagluster\fR agent +.IP "\fB$PCP_LOG_DIR/pmcd/gluster.log\fR" 4 +default log file for error messages from \fBpmdagluster\fR +.SH PCP ENVIRONMENT +Environment variables with the prefix \fBPCP_\fR are used to parameterize +the file and directory names used by \fBPCP\fR. On each installation, the +file \fB/etc/pcp.conf\fR contains the local values for these variables. +The \fB$PCP_CONF\fR variable may be used to specify an alternative +configuration file, as described in \fIpcp.conf\fR(5). +.SH SEE ALSO +.BR pmcd (1), +.BR pminfo (1), +.BR pmstore (1), +and +.BR gluster (8) diff --git a/man/man1/pmdaib.1 b/man/man1/pmdaib.1 new file mode 100644 index 0000000..1e3edcf --- /dev/null +++ b/man/man1/pmdaib.1 @@ -0,0 +1,121 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2009 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.TH PMDAIB 1 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmdaib\f1 \- Infiniband performance metrics domain agent (PMDA) +.SH SYNOPSYS +\f3$PCP_PMDAS_DIR/infiniband/pmdaib\f1 +[\f3\-c\f1 \f2configFile\f1] +[\f3\-D\f1 \f2debug\f1] +[\f3\-d\f1 \f2domain\f1] +[\f3\-l\f1 \f2logfile\f1] +[\f3\-w\f1] +.SH DESCRIPTION +.B pmdaib +is a Performance Metrics Domain Agent (PMDA) which exports information and +performance metrics about local Infiniband HCAs and local or remote Infiniband GUIDs. +.PP +A brief description of the +.B pmdaib +command line options follows: +.TP 5 +.B \-c +Location of the config file. By default, the config file is named +.BR $PCP_PMDAS_DIR/infiniband/config. +See +.BR "CONFIG FILE" +for more information. +.TP +.B -D +A debug values, as specified by +.B pmdbg (1) +.TP +.B \-d +Specify an alternate performance metrics +.I domain +number. Almost never necessary. +.TP +.B \-l +Location of the log file. By default, a log file named +.I ib.log +is written to +.BR $PCP_LOG_DIR/pmcd . +If the log file cannot be created or is not writable, output +is written to the standard error instead. +.TP +.B \-w +Write out the default config file to +.BR $PCP_PMDAS_DIRS/infiniband +and exit immediately. The written config file will contain the local HCA ports. +It will not overwrite an existing file. This argument should only be used to create +the template config file and should never appear in +.I pmcd.conf. +See +.BR "CONFIG FILE" +for more information on the file format and on monitoring +remote GUIDs. +.SH CONFIG FILE +By default, the PMDA will operate without using a config file. In this mode of operation +the local HCA ports will be monitored. Note that if a new HCA is added to the machine that +instance domain naming may change because it will always be based on the kernel's naming. +.PP +In cases where this is not acceptable, or in the case where monitoring remote Infiniband +ports is required, a config file must be created. A "template" file can be created by +running the +.B pmdaib +daemon with the +.B \-w +argument. This will create a config file with the local ports and GUIDs. +.PP +If the config file is +.I executable +then it will be run and the output will be used as the config file. +.PP +The config file is composed of line-based records. Blank lines and everything after +the +.I hash (#) +character are ignored. Each line has 6 fields: +.PP +[\f3instName\f1] [\f3portGUID\f1] [\f3portNum\f1] via [\f3localPortName\f1]:[\f3localPortNum\f1] +.PP +The first field is used to give a static instance name to the Infiniband port that +has a specific GUID. All of the other fields must be properly specified in order +to monitor a particular port. +.PP +For example, to monitor port 1 of the local HCA called 'mthca0' a possible config file +line would be: +.PP +myPort1 0xdeadbeef01234567 1 via mthca0:1 +.PP +Remote ports can be easily monitored by specifying the GUID of the HCA or switch and +specifying the remote port number. The \f3localPortName\f1:\f3localPortNum\f1 tuple +specifies which local HCA and port to use as the "first hop" in contacting the remote +GUID. E.g., to monitor port 13 of a remote switch which is connected to the fabric +on the first port of the second HCA: +.PP +switch13 0xfeeffeefabcdabcd 13 via mthca1:1 +.SH LOCAL CONTEXT +The Infiniband pmda also supports accessing the metrics via +.B PM_CONTEXT_LOCAL +when using the PMAPI interface. In order to use the Infiniband pmda in this way, +set the environment variable +.B PMDA_LOCAL_IB +prior to calling +.B pmNewContext(3). +.SH SEE ALSO +.BR pmcd(1), +.BR PMAPI(3), +.BR pmContextNew(3), +.BR ibnetdiscover(8). diff --git a/man/man1/pmdajbd2.1 b/man/man1/pmdajbd2.1 new file mode 100644 index 0000000..58e2129 --- /dev/null +++ b/man/man1/pmdajbd2.1 @@ -0,0 +1,161 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2014 Red Hat. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.TH PMDAJBD2 1 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmdajbd2\f1 \- journal block device (JBD) performance metrics domain agent (PMDA) +.SH SYNOPSIS +\f3$PCP_PMDAS_DIR/jbd2/pmdajbd2\f1 +[\f3\-d\f1 \f2domain\f1] +[\f3\-l\f1 \f2logfile\f1] +[\f3\-j\f1 \f2path\f1] +[\f3\-U\f1 \f2username\f1] +.SH DESCRIPTION +.B pmdajbd2 +is a Performance Metrics Domain Agent (PMDA) which extracts +performance metrics from the Journal Block Device subsystem +(version 2) in the Linux kernel. +These metrics are exported by the kernel in procfs files, +one file per block device. +The JBD2 subsystem is used by several filesystems including +ext3, ext4 and ocfs2. +.PP +The +.B jbd2 +PMDA exports metrics that measure detailed journal transaction +information, such as time spent waiting and locked, request +rates, blocks used and so on. +.PP +A brief description of the +.B pmdajbd2 +command line options follows (these are only relevant when +running the PMDA as a daemon, and not as a shared library): +.TP 5 +.B \-d +It is absolutely crucial that the performance metrics +.I domain +number specified here is unique and consistent. +That is, +.I domain +should be different for every PMDA on the one host, and the same +.I domain +number should be used for the same PMDA on all hosts. +.TP +.B \-l +Location of the log file. By default, when running as a daemon +a log file named +.I jbd2.log +is written in the current directory of +when +.B pmdajbd2 +is started, i.e. +.BR $PCP_LOG_DIR/pmcd . +If the log file cannot +be created or is not writable, output is written to the standard error instead. +When running in shared library mode, and diagnostic information will +be written into the +.B pmcd +log file, namely +.BR $PCP_LOG_DIR/pmcd/pmcd.log . +.TP +.B \-j +Allows an alternate path to the jbd2 statistics files to be specified. +The default path is +.IR /proc/fs/jbd2 . +.TP +.B \-U +User account under which to run the agent. +The default is the unprivileged "pcp" account in current versions of PCP, +but in older versions the superuser account ("root") was used by default. +.SH INSTALLATION +This PMDA is installed by default and in the shared library +mode (rather than as a separate daemon to +.BR pmcd (1)). +Thus, the names, help text and values for the jbd2 performance metrics +should always be available. +.PP +If you do not use these metrics you can remove this PMDA, do the +following as root: +.PP +.ft CW +.nf +.in +0.5i +# cd $PCP_PMDAS_DIR/jbd2 +# ./Remove +.in +.fi +.ft 1 +.PP +If you want to enable the installation again, do the following as root: +.PP +.ft CW +.nf +.in +0.5i +# cd $PCP_PMDAS_DIR/jbd2 +# ./Install +.in +.fi +.ft 1 +.PP +.B pmdajbd2 +is launched by +.BR pmcd (1) +and should never be executed directly. +The Install and Remove scripts notify +.BR pmcd (1) +when the agent is installed or removed. +.SH FILES +.PD 0 +.TP 10 +.B $PCP_PMCDCONF_PATH +command line options used to launch +.B pmdajbd2 +.TP 10 +.B $PCP_PMDAS_DIR/jbd2/help +default help text file for the jbd2 metrics +.TP 10 +.B $PCP_PMDAS_DIR/jbd2/Install +installation script for the +.B pmdajbd2 +agent +.TP 10 +.B $PCP_PMDAS_DIR/jbd2/Remove +undo installation script for the +.B pmdajbd2 +agent +.TP 10 +.B $PCP_LOG_DIR/pmcd/jbd2.log +default log file for error messages and other information from +.B pmdajbd2 +.PD +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.I /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). +.SH SEE ALSO +.BR PCPIntro (1), +.BR pmcd (1), +.BR pcp.conf (5) +and +.BR pcp.env (5). diff --git a/man/man1/pmdakernel.1 b/man/man1/pmdakernel.1 new file mode 100644 index 0000000..6d9b7bf --- /dev/null +++ b/man/man1/pmdakernel.1 @@ -0,0 +1,155 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2014 Red Hat. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.TH "KERNEL PMDAS" 1 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmdaaix\f1, +\f3pmdadarwin\f1, +\f3pmdafreebsd\f1, +\f3pmdalinux\f1, +\f3pmdanetbsd\f1, +\f3pmdasolaris\f1, +\f3pmdawindows\f1 \- operating system kernel performance metrics domain agents +.SH SYNOPSIS +\f3$PCP_PMDAS_DIR/aix/pmdaaix\f1 +[\f3\-d\f1 \f2domain\f1] +[\f3\-l\f1 \f2logfile\f1] +[\f3\-U\f1 \f2username\f1] +.br +\f3$PCP_PMDAS_DIR/darwin/pmdadarwin\f1 +[\f3\-d\f1 \f2domain\f1] +[\f3\-l\f1 \f2logfile\f1] +[\f3\-U\f1 \f2username\f1] +.br +\f3$PCP_PMDAS_DIR/freebsd/pmdafreebsd\f1 +[\f3\-d\f1 \f2domain\f1] +[\f3\-l\f1 \f2logfile\f1] +[\f3\-U\f1 \f2username\f1] +.br +\f3$PCP_PMDAS_DIR/linux/pmdalinux\f1 +[\f3\-d\f1 \f2domain\f1] +[\f3\-l\f1 \f2logfile\f1] +[\f3\-U\f1 \f2username\f1] +.br +\f3$PCP_PMDAS_DIR/netbsd/pmdanetbsd\f1 +[\f3\-d\f1 \f2domain\f1] +[\f3\-l\f1 \f2logfile\f1] +[\f3\-U\f1 \f2username\f1] +.br +\f3$PCP_PMDAS_DIR/solaris/pmdasolaris\f1 +[\f3\-d\f1 \f2domain\f1] +[\f3\-l\f1 \f2logfile\f1] +[\f3\-U\f1 \f2username\f1] +.br +\f3$PCP_PMDAS_DIR/windows/pmdawindows\f1 +[\f3\-d\f1 \f2domain\f1] +[\f3\-l\f1 \f2logfile\f1] +[\f3\-U\f1 \f2username\f1] +.SH DESCRIPTION +Each supported platform has a kernel Performance Metrics Domain +Agent (PMDA) which extracts performance metrics from the kernel +of that platfrom. +A variety of platform-specific metrics are available, with an +equally varied set of access mechanisms - typically this involves +special system calls, or reading from files in kernel virtual +filesystems such as the Linux +.I sysfs +and +.I procfs +filesystems. +.PP +The platform kernel PMDA is one of the most critical components +of the PCP installation, and must be as efficient and reliable +as possible. +In all installations the default kernel PMDA will be installed +as a shared library and thus executes directly within the +.BR pmcd (1) +process. +This slightly reduces overheads associated with querying the +metadata and values associated with these metrics (no message +passing is required). +.PP +Unlike many other PMDAs, the kernel PMDA exports a number of +metric namespace subtrees, such as kernel, network, swap, mem, +ipc, filesys, nfs, disk and hinv (hardware inventory). +.PP +Despite usually running as shared libraries, most installations +also include a stand-alone executable for the kernel PMDA. +This is to aid profiling and debugging activities, with +.BR dbpmda (1) +for example. +In this case (but not for shared libraries), the following +command line options are available: +.TP 5 +.B \-d +It is absolutely crucial that the performance metrics +.I domain +number specified here is unique and consistent. +That is, +.I domain +should be different for every PMDA on the one host, and the same +.I domain +number should be used for the same PMDA on all hosts. +.TP +.B \-l +Location of the log file. By default, a log file named +.I [platform].log +is written in the current directory of +.BR pmcd (1) +when +.B pmda[platform] +is started, i.e. +.BR $PCP_LOG_DIR/pmcd . +If the log file cannot +be created or is not writable, output is written to the standard error instead. +.TP +.B \-U +User account under which to run the agent. +The default is the unprivileged "pcp" account in current versions of PCP, +but in older versions the superuser account ("root") was used by default. +.SH INSTALLATION +Access to the names, help text and values for the kernel performance +metrics is available by default - unlike most other agents, no action +is required to enable them and they should not be removed. +.SH FILES +.PD 0 +.TP 10 +.B $PCP_PMDAS_DIR/[platform]/help +default help text file for the the kernel metrics +.TP 10 +.B $PCP_LOG_DIR/pmcd/pmcd.log +default log file for error messages and other information from +the kernel PMDA. +.PD +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.I /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). +.SH SEE ALSO +.BR PCPIntro (1), +.BR dbpmda (1) +.BR pmcd (1), +.BR pcp.conf (5) +and +.BR pcp.env (5). diff --git a/man/man1/pmdalmsensors.1 b/man/man1/pmdalmsensors.1 new file mode 100644 index 0000000..e266975 --- /dev/null +++ b/man/man1/pmdalmsensors.1 @@ -0,0 +1,138 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2014 Red Hat. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.TH PMDALMSENSORS 1 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmdalmsensors\f1 \- Linux hardware monitoring performance metrics domain agent (PMDA) +.SH SYNOPSIS +\f3$PCP_PMDAS_DIR/lmsensors/pmdalmsensors\f1 +[\f3\-d\f1 \f2domain\f1] +[\f3\-l\f1 \f2logfile\f1] +[\f3\-U\f1 \f2username\f1] +.SH DESCRIPTION +.B pmdalmsensors +is a Performance Metrics Domain Agent (PMDA) which extracts +performance metrics describing the state of hardware using +the lm-sensors on compatible motherboards. +.PP +The +.B lmsensors +PMDA exports metrics that measure fan speeds, core temperatures +and voltage levels. +.PP +A brief description of the +.B pmdalmsensors +command line options follows: +.TP 5 +.B \-d +It is absolutely crucial that the performance metrics +.I domain +number specified here is unique and consistent. +That is, +.I domain +should be different for every PMDA on the one host, and the same +.I domain +number should be used for the same PMDA on all hosts. +.TP +.B \-l +Location of the log file. By default, a log file named +.I lmsensors.log +is written in the current directory of +.BR pmcd (1) +when +.B pmdalmsensors +is started, i.e. +.B $PCP_LOG_DIR/pmcd . +If the log file cannot +be created or is not writable, output is written to the standard error instead. +.TP +.B \-U +User account under which to run the agent. +The default is the unprivileged "pcp" account in current versions of PCP, +but in older versions the superuser account ("root") was used by default. +.SH INSTALLATION +If you want access to the names, help text and values for the lmsensors +performance metrics, do the following as root: +.PP +.ft CW +.nf +.in +0.5i +# cd $PCP_PMDAS_DIR/lmsensors +# ./Install +.in +.fi +.ft 1 +.PP +If you want to undo the installation, do the following as root: +.PP +.ft CW +.nf +.in +0.5i +# cd $PCP_PMDAS_DIR/lmsensors +# ./Remove +.in +.fi +.ft 1 +.PP +.B pmdalmsensors +is launched by +.BR pmcd (1) +and should never be executed directly. +The Install and Remove scripts notify +.BR pmcd (1) +when the agent is installed or removed. +.SH FILES +.PD 0 +.TP 10 +.B $PCP_PMCDCONF_PATH +command line options used to launch +.B pmdalmsensors +.TP 10 +.B $PCP_PMDAS_DIR/lmsensors/help +default help text file for the lmsensors metrics +.TP 10 +.B $PCP_PMDAS_DIR/lmsensors/Install +installation script for the +.B pmdalmsensors +agent +.TP 10 +.B $PCP_PMDAS_DIR/lmsensors/Remove +undo installation script for the +.B pmdalmsensors +agent +.TP 10 +.B $PCP_LOG_DIR/pmcd/lmsensors.log +default log file for error messages and other information from +.B pmdalmsensors +.PD +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.I /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). +.SH SEE ALSO +.BR PCPIntro (1), +.BR pmcd (1), +.BR pcp.conf (5) +and +.BR pcp.env (5). diff --git a/man/man1/pmdalogger.1 b/man/man1/pmdalogger.1 new file mode 100644 index 0000000..846c535 --- /dev/null +++ b/man/man1/pmdalogger.1 @@ -0,0 +1,184 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2014 Red Hat. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.TH PMDALOGGER 1 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmdalogger\f1 \- log file performance metrics domain agent (PMDA) +.SH SYNOPSIS +\f3$PCP_PMDAS_DIR/logger/pmdalogger\f1 +[\f3\-d\f1 \f2domain\f1] +[\f3\-l\f1 \f2logfile\f1] +[\f3\-m\f1 \f2memory\f1] +[\f3\-s\f1 \f2interval\f1] +[\f3\-U\f1 \f2username\f1] +[\f2configfile\f1] +.SH DESCRIPTION +.B pmdalogger +is a configurable log file monitoring Performance Metrics Domain +Agent (PMDA). +It can be seen as analagous to the +.B \-f +option to +.BR tail (1) +and converts each new log line into a performance event. +It was the first PMDA to make extensive use of event metrics, which +can be consumed by client tools like +.BR pmevent (1). +.PP +The +.B logger +PMDA exports both event-style metrics reflecting timestamped event records +for text logged to a file (or set of files or output from a process), +as well as the more orthodox sample-style metrics such as event counts +and throughput size values. +.PP +The PMDA is configured via a +.I configfile +which contains one line for each source of events (file or process). +This file is setup by the Install script described in the later +section on ``INSTALLATION'' of the PMDA. +.PP +A brief description of the +.B pmdalogger +command line options follows: +.TP 5 +.B \-d +It is absolutely crucial that the performance metrics +.I domain +number specified here is unique and consistent. +That is, +.I domain +should be different for every PMDA on the one host, and the same +.I domain +number should be used for the same PMDA on all hosts. +.TP +.B \-l +Location of the log file. By default, a log file named +.I logger.log +is written in the current directory of +.BR pmcd (1) +when +.B pmdalogger +is started, i.e. +.BR $PCP_LOG_DIR/pmcd . +If the log file cannot +be created or is not writable, output is written to the standard error instead. +.TP +.B \-m +Limit the physical memory used by the PMDA to buffer event records to +.I maxsize +bytes. +As log events arrive at the PMDA, they must be buffered until individual +client tools request the next batch since their previous batch of events. +The default maximum is 2 megabytes. +.TP +.B \-s +Sets the polling interval for detecting newly arrived log lines. +Mirrors the same option from the +.BR tail (1) +command. +.TP +.B \-U +User account under which to run the agent. +The default is the unprivileged "pcp" account in current versions of PCP, +but in older versions the superuser account ("root") was used by default. +.SH INSTALLATION +If you want access to the names, help text and values for the logger +performance metrics, do the following as root: +.PP +.ft CW +.nf +.in +0.5i +# cd $PCP_PMDAS_DIR/logger +# ./Install +.in +.fi +.ft 1 +.PP +This is an interactive installation process which prompts for each +log file path to be monitored (or command to be run), a metric +instance name to identify it, and whether access should be restricted +(refer to the +.B \-x +option to +.BR pmevent (1) +for further details). +.PP +If you want to undo the installation, do the following as root: +.PP +.ft CW +.nf +.in +0.5i +# cd $PCP_PMDAS_DIR/logger +# ./Remove +.in +.fi +.ft 1 +.PP +.B pmdalogger +is launched by +.BR pmcd (1) +and should never be executed directly. +The Install and Remove scripts notify +.BR pmcd (1) +when the agent is installed or removed. +.SH FILES +.PD 0 +.TP 10 +.B $PCP_PMCDCONF_PATH +command line options used to launch +.B pmdalogger +.TP 10 +.B $PCP_PMDAS_DIR/logger/logger.conf +default configuration file for the logger metrics +.TP 10 +.B $PCP_PMDAS_DIR/logger/help +default help text file for the logger metrics +.TP 10 +.B $PCP_PMDAS_DIR/logger/Install +installation script for the +.B pmdalogger +agent +.TP 10 +.B $PCP_PMDAS_DIR/logger/Remove +undo installation script for the +.B pmdalogger +agent +.TP 10 +.B $PCP_LOG_DIR/pmcd/logger.log +default log file for error messages and other information from +.B pmdalogger +.PD +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.I /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). +.SH SEE ALSO +.BR PCPIntro (1), +.BR pmevent (1), +.BR pmcd (1), +.BR tail (1), +.BR pcp.conf (5) +and +.BR pcp.env (5). diff --git a/man/man1/pmdalustrecomm.1 b/man/man1/pmdalustrecomm.1 new file mode 100644 index 0000000..dd5fa85 --- /dev/null +++ b/man/man1/pmdalustrecomm.1 @@ -0,0 +1,141 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2014 Red Hat. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.TH PMDALUSTERCOMM 1 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmdalustrecomm\f1 \- Lustre filesystem comms performance metrics domain agent (PMDA) +.SH SYNOPSIS +\f3$PCP_PMDAS_DIR/lustrecomm/pmdalustrecomm\f1 +[\f3\-d\f1 \f2domain\f1] +[\f3\-l\f1 \f2logfile\f1] +[\f3\-U\f1 \f2username\f1] +.SH DESCRIPTION +.B pmdalustrecomm +is a Performance Metrics Domain Agent (PMDA) which extracts +performance metrics from the Linux procfs filesystem about +the state of various aspects of the Lustre filesystem. +.PP +The +.B lustrecomm +PMDA exports metrics that focus on distributed communication +in the filesystem, including metrics related to timeouts, +network drops, send/recv information and route lengths. +However, it also covers the memory use of some of the Lustre +filesystem components. +.PP +A brief description of the +.B pmdalustrecomm +command line options follows: +.TP 5 +.B \-d +It is absolutely crucial that the performance metrics +.I domain +number specified here is unique and consistent. +That is, +.I domain +should be different for every PMDA on the one host, and the same +.I domain +number should be used for the same PMDA on all hosts. +.TP +.B \-l +Location of the log file. By default, a log file named +.I lustrecomm.log +is written in the current directory of +.BR pmcd (1) +when +.B pmdalustrecomm +is started, i.e. +.BR $PCP_LOG_DIR/pmcd . +If the log file cannot +be created or is not writable, output is written to the standard error instead. +.TP +.B \-U +User account under which to run the agent. +The default is the unprivileged "pcp" account in current versions of PCP, +but in older versions the superuser account ("root") was used by default. +.SH INSTALLATION +If you want access to the names, help text and values for the lustrecomm +performance metrics, do the following as root: +.PP +.ft CW +.nf +.in +0.5i +# cd $PCP_PMDAS_DIR/lustrecomm +# ./Install +.in +.fi +.ft 1 +.PP +If you want to undo the installation, do the following as root: +.PP +.ft CW +.nf +.in +0.5i +# cd $PCP_PMDAS_DIR/lustrecomm +# ./Remove +.in +.fi +.ft 1 +.PP +.B pmdalustrecomm +is launched by +.BR pmcd (1) +and should never be executed directly. +The Install and Remove scripts notify +.BR pmcd (1) +when the agent is installed or removed. +.SH FILES +.PD 0 +.TP 10 +.B $PCP_PMCDCONF_PATH +command line options used to launch +.B pmdalustrecomm +.TP 10 +.B $PCP_PMDAS_DIR/lustrecomm/help +default help text file for the lustrecomm metrics +.TP 10 +.B $PCP_PMDAS_DIR/lustrecomm/Install +installation script for the +.B pmdalustrecomm +agent +.TP 10 +.B $PCP_PMDAS_DIR/lustrecomm/Remove +undo installation script for the +.B pmdalustrecomm +agent +.TP 10 +.B $PCP_LOG_DIR/pmcd/lustrecomm.log +default log file for error messages and other information from +.B pmdalustrecomm +.PD +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.I /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). +.SH SEE ALSO +.BR PCPIntro (1), +.BR pmcd (1), +.BR pcp.conf (5) +and +.BR pcp.env (5). diff --git a/man/man1/pmdamailq.1 b/man/man1/pmdamailq.1 new file mode 100644 index 0000000..f8bdd42 --- /dev/null +++ b/man/man1/pmdamailq.1 @@ -0,0 +1,189 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2012 Red Hat. +.\" Copyright (c) 2000 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMDAMAILQ 1 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmdamailq\f1 \- mail queue performance metrics domain agent (PMDA) +.SH SYNOPSIS +\f3$PCP_PMDAS_DIR/mailq/pmdamailq\f1 +[\f3\-b\f1 \f2binlist\f1] +[\f3\-d\f1 \f2domain\f1] +[\f3\-l\f1 \f2logfile\f1] +[\f3\-r\f1 \f2regex\f1] +[\f3\-U\f1 \f2username\f1] +[\f2queuedir\f1] +.SH DESCRIPTION +.B pmdamailq +is a Performance Metrics Domain Agent (PMDA) which extracts +performance metrics describing the state of the e-mail queues +managed by +.BR sendmail (1) +and other mail transfer agents. +.PP +The +.B mailq +PMDA exports metrics that measure the total number of entries +in the mail queue, and the subtotals for entries that have +been queued for various time periods. +.PP +A brief description of the +.B pmdamailq +command line options follows: +.TP 5 +.B \-b +The +.I binlist +argument specifies a list of delay thresholds used to ``bin'' the +entries in the queue into a a histogram based on how long +the entry has been in the mail queue. +The default thresholds are: +1 hour, 4 hours, 8 hours, 1 day, 3 days and 7 days. +The entries in +.I binlist +are comma separated time intervals, using the syntax described in +.BR PCPIntro (1) +for an update or reporting interval, e.g. the default list could be +specified using the value +.BR "1hr,4hrs,8hrs,1day,3days,7days" . +.RS +.PP +Values in +.I binlist +are assumed to be in ascending order, and mail items in the queue less +than the first threshold are binned into a special bin labeled ``recent''. +.RE +.TP +.B \-d +It is absolutely crucial that the performance metrics +.I domain +number specified here is unique and consistent. +That is, +.I domain +should be different for every PMDA on the one host, and the same +.I domain +number should be used for the same PMDA on all hosts. +.TP +.B \-l +Location of the log file. By default, a log file named +.I mailq.log +is written in the current directory of +.BR pmcd (1) +when +.B pmdamailq +is started, i.e. +.B $PCP_LOG_DIR/pmcd . +If the log file cannot +be created or is not writable, output is written to the standard error instead. +.TP +.B \-r +Use an extended regular expression to match file names in the mail queue +directory, rather than assuming all "df" prefixed files in the directory +are mail files (the "df" prefix is the +.B sendmail +convention, but this convention is not followed by other mail daemons). +The +.I regex +pattern specified should conform to the POSIX format described in +.BR regex (3), +and it describes file names that should be considered mail. +.TP 5 +.B \-U +User account under which to run the agent. +The default is the unprivileged "pcp" account in current versions of PCP, +but in older versions the superuser account ("root") was used by default. +.PP +The optional +.I queuedir +argument defines the directory in which +.B pmdamailq +expects to find the mail queue. +The default is +.BR /var/spool/mqueue . +.SH INSTALLATION +If you want access to the names, help text and values for the mailq +performance metrics, do the following as root: +.PP +.ft CW +.nf +.in +0.5i +# cd $PCP_PMDAS_DIR/mailq +# ./Install +.in +.fi +.ft 1 +.PP +If you want to undo the installation, do the following as root: +.PP +.ft CW +.nf +.in +0.5i +# cd $PCP_PMDAS_DIR/mailq +# ./Remove +.in +.fi +.ft 1 +.PP +.B pmdamailq +is launched by +.BR pmcd (1) +and should never be executed directly. +The Install and Remove scripts notify +.BR pmcd (1) +when the agent is installed or removed. +.SH FILES +.PD 0 +.TP 10 +.B $PCP_PMCDCONF_PATH +command line options used to launch +.B pmdamailq +.TP 10 +.B $PCP_PMDAS_DIR/mailq/help +default help text file for the mailq metrics +.TP 10 +.B $PCP_PMDAS_DIR/mailq/Install +installation script for the +.B pmdamailq +agent +.TP 10 +.B $PCP_PMDAS_DIR/mailq/Remove +undo installation script for the +.B pmdamailq +agent +.TP 10 +.B $PCP_LOG_DIR/pmcd/mailq.log +default log file for error messages and other information from +.B pmdamailq +.PD +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.I /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). +.SH SEE ALSO +.BR PCPIntro (1), +.BR pmcd (1), +.BR pcp.conf (5) +and +.BR pcp.env (5). diff --git a/man/man1/pmdammv.1 b/man/man1/pmdammv.1 new file mode 100644 index 0000000..859b151 --- /dev/null +++ b/man/man1/pmdammv.1 @@ -0,0 +1,177 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2014 Red Hat. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.TH PMDAMMV 1 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmdammv\f1 \- memory mapped values performance metrics domain agent (PMDA) +.SH SYNOPSIS +\f3$PCP_PMDAS_DIR/mmv/pmdammv\f1 +[\f3\-d\f1 \f2domain\f1] +[\f3\-l\f1 \f2logfile\f1] +[\f3\-U\f1 \f2username\f1] +.SH DESCRIPTION +.B pmdammv +is a Performance Metrics Domain Agent (PMDA) which exports +application level performance metrics using memory mapped files. +It offers an extremely low overhead instrumentation facility +that is well-suited to long running, mission critical applications +where it is desirable to have performance metrics and availability +information permanently enabled. +.PP +The +.B mmv +PMDA exports instrumentation that has been added to an application +using the MMV APIs (refer to +.BR mmv_stats_init (3) +and +.BR mmv (5) +for further details). +These APIs can be called from several languages, including C, C++, +Perl, Python and Java (via the separate ``Parfait'' class library). +.PP +A brief description of the +.B pmdammv +command line options follows: +.TP 5 +.B \-d +It is absolutely crucial that the performance metrics +.I domain +number specified here is unique and consistent. +That is, +.I domain +should be different for every PMDA on the one host, and the same +.I domain +number should be used for the same PMDA on all hosts. +.TP +.B \-l +Location of the log file. By default, a log file named +.I mmv.log +is written in the current directory of +.BR pmcd (1) +when +.B pmdammv +is started, i.e. +.BR $PCP_LOG_DIR/pmcd . +If the log file cannot +be created or is not writable, output is written to the standard error instead. +.TP +.B \-U +User account under which to run the agent. +The default is the unprivileged "pcp" account in current versions of PCP, +but in older versions the superuser account ("root") was used by default. +.SH INSTALLATION +If you want access to the names, help text and values for the mmv +performance metrics, do the following as root: +.PP +.ft CW +.nf +.in +0.5i +# cd $PCP_PMDAS_DIR/mmv +# ./Install +.in +.fi +.ft 1 +.PP +Note that the default mechanism for sharing memory mapped values +between instrumented applications and the +.B mmv +PMDA involves the creation of a world-writeable +.I $PCP_TMP_DIR/mmv +directory with the sticky-bit set (similar to +.I /tmp +and +.IR /var/tmp , +for example). +This suffices to allow any application, running under any user account, +to communicate with the PMDA (which runs under the "pcp" account by +default). +This may not be desirable for every environment, and one should consider +the security implications of any directory setup like this (similar +classes of issues exist as those that affect the system temporary file +directories). +.PP +The installation process will not overwrite any existing +.I $PCP_TMP_DIR/mmv +directory. +Thus it is possible to implement an alternate permissions strategy with +no world-writable directory for sharing files - any directory readable +by user or group "pcp" will suffice. +.PP +If you want to undo the installation, do the following as root: +.PP +.ft CW +.nf +.in +0.5i +# cd $PCP_PMDAS_DIR/mmv +# ./Remove +.in +.fi +.ft 1 +.PP +.B pmdammv +is launched by +.BR pmcd (1) +and should never be executed directly. +The Install and Remove scripts notify +.BR pmcd (1) +when the agent is installed or removed. +.SH FILES +.PD 0 +.TP 10 +.B $PCP_PMCDCONF_PATH +command line options used to launch +.B pmdammv +.TP 10 +.B $PCP_TMP_DIR/mmv +directory housing memory mapped value files +.TP 10 +.B $PCP_PMDAS_DIR/mmv/help +default help text file for the mmv metrics +.TP 10 +.B $PCP_PMDAS_DIR/mmv/Install +installation script for the +.B pmdammv +agent +.TP 10 +.B $PCP_PMDAS_DIR/mmv/Remove +undo installation script for the +.B pmdammv +agent +.TP 10 +.B $PCP_LOG_DIR/pmcd/mmv.log +default log file for error messages and other information from +.B pmdammv +.PD +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.I /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). +.SH SEE ALSO +.BR PCPIntro (1), +.BR pmcd (1), +.BR mmv_stats_init (3), +.BR mmv (5), +.BR pcp.conf (5) +and +.BR pcp.env (5). diff --git a/man/man1/pmdamounts.1 b/man/man1/pmdamounts.1 new file mode 100644 index 0000000..2de6f41 --- /dev/null +++ b/man/man1/pmdamounts.1 @@ -0,0 +1,147 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2014 Red Hat. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.TH PMDAMOUNTS 1 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmdamounts\f1 \- filesystem mounts performance metrics domain agent (PMDA) +.SH SYNOPSIS +\f3$PCP_PMDAS_DIR/mounts/pmdamounts\f1 +[\f3\-d\f1 \f2domain\f1] +[\f3\-l\f1 \f2logfile\f1] +[\f3\-U\f1 \f2username\f1] +.SH DESCRIPTION +.B pmdamounts +is a simple Performance Metrics Domain Agent (PMDA) which +monitors availability of a given set of filesystem mounts. +.PP +The +.B mounts +PMDA exports metrics that reflect whether the configured +filesystems are mounted ("up") or not. +The list of mount points to monitor is specified via the +.I $PCP_PMDAS_DIR/mounts/mounts.conf +file which simply contains one line for each mount point. +.PP +Note that the platform kernel PMDA exports a more extensive +set of filesystem metrics for every mounted filesystem \- +this PMDA is primarily intended for availability monitoring +using the +.I mounts.up +metric. +.PP +A brief description of the +.B pmdamounts +command line options follows: +.TP 5 +.B \-d +It is absolutely crucial that the performance metrics +.I domain +number specified here is unique and consistent. +That is, +.I domain +should be different for every PMDA on the one host, and the same +.I domain +number should be used for the same PMDA on all hosts. +.TP +.B \-l +Location of the log file. By default, a log file named +.I mounts.log +is written in the current directory of +.BR pmcd (1) +when +.B pmdamounts +is started, i.e. +.BR $PCP_LOG_DIR/pmcd . +If the log file cannot +be created or is not writable, output is written to the standard error instead. +.TP +.B \-U +User account under which to run the agent. +The default is the unprivileged "pcp" account in current versions of PCP, +but in older versions the superuser account ("root") was used by default. +.SH INSTALLATION +If you want access to the names, help text and values for the mounts +performance metrics, do the following as root: +.PP +.ft CW +.nf +.in +0.5i +# cd $PCP_PMDAS_DIR/mounts +# ./Install +.in +.fi +.ft 1 +.PP +If you want to undo the installation, do the following as root: +.PP +.ft CW +.nf +.in +0.5i +# cd $PCP_PMDAS_DIR/mounts +# ./Remove +.in +.fi +.ft 1 +.PP +.B pmdamounts +is launched by +.BR pmcd (1) +and should never be executed directly. +The Install and Remove scripts notify +.BR pmcd (1) +when the agent is installed or removed. +.SH FILES +.PD 0 +.TP 10 +.B $PCP_PMCDCONF_PATH +command line options used to launch +.B pmdamounts +.TP 10 +.B $PCP_PMDAS_DIR/mounts/help +default help text file for the mounts metrics +.TP 10 +.B $PCP_PMDAS_DIR/mounts/Install +installation script for the +.B pmdamounts +agent +.TP 10 +.B $PCP_PMDAS_DIR/mounts/Remove +undo installation script for the +.B pmdamounts +agent +.TP 10 +.B $PCP_LOG_DIR/pmcd/mounts.log +default log file for error messages and other information from +.B pmdamounts +.PD +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.I /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). +.SH SEE ALSO +.BR PCPIntro (1), +.BR pmcd (1), +.BR pcp.conf (5) +and +.BR pcp.env (5). diff --git a/man/man1/pmdanvidia.1 b/man/man1/pmdanvidia.1 new file mode 100644 index 0000000..47fcbf0 --- /dev/null +++ b/man/man1/pmdanvidia.1 @@ -0,0 +1,136 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2014 Red Hat. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.TH PMDANVIDIA 1 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmdanvidia\f1 \- nvidia gpu metrics domain agent (PMDA) +.SH SYNOPSIS +\f3$PCP_PMDAS_DIR/nvidia/pmdanvidia\f1 +[\f3\-d\f1 \f2domain\f1] +[\f3\-l\f1 \f2logfile\f1] +.SH DESCRIPTION +.B pmdanvidia +is a Performance Metrics Domain Agent (PMDA) which extracts +performance metrics describing the metrics available on NVIDIA +GPU cards via the NVML library. +.PP +The +.B nvidia +PMDA exports metrics that measure gpu activity, memory utilization, +fan speed, etc on NVIDIA Tesla and Quadro cards. Metrics are unlikely +to be available for consumer class cards. +.PP +A brief description of the +.B pmdanvidia +command line options follows: +.TP 5 +.B \-d +It is absolutely crucial that the performance metrics +.I domain +number specified here is unique and consistent. +That is, +.I domain +should be different for every PMDA on the one host, and the same +.I domain +number should be used for the same PMDA on all hosts. +.TP +.B \-l +Location of the log file. By default, a log file named +.I nvidia.log +is written in the current directory of +.BR pmcd (1) +when +.B pmdanvidia +is started, i.e. +.BR $PCP_LOG_DIR/pmcd . +If the log file cannot +be created or is not writable, output is written to the standard error instead. +.SH INSTALLATION +The +.B nvidia +PMDA is not installed and available by default. +If you want to undo the installation, do the following as root: +.PP +.ft CW +.nf +.in +0.5i +# cd $PCP_PMDAS_DIR/nvidia +# ./Remove +.in +.fi +.ft 1 +.PP +If you want to establish access to the names, help text and values for the nvidia +performance metrics once more, after removal, do the following as root: +.PP +.ft CW +.nf +.in +0.5i +# cd $PCP_PMDAS_DIR/nvidia +# ./Install +.in +.fi +.ft 1 +.PP +.B pmdanvidia +is launched by +.BR pmcd (1) +and should never be executed directly. +The Install and Remove scripts notify +.BR pmcd (1) +when the agent is installed or removed. +.SH FILES +.PD 0 +.TP 10 +.B $PCP_PMCDCONF_PATH +command line options used to launch +.B pmdanvidia +.TP 10 +.B $PCP_PMDAS_DIR/nvidia/help +default help text file for the nvidia metrics +.TP 10 +.B $PCP_PMDAS_DIR/nvidia/Install +installation script for the +.B pmdanvidia +agent +.TP 10 +.B $PCP_PMDAS_DIR/nvidia/Remove +undo installation script for the +.B pmdanvidia +agent +.TP 10 +.B $PCP_LOG_DIR/pmcd/nvidia.log +default log file for error messages and other information from +.B pmdanvidia +.PD +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.I /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). +.SH SEE ALSO +.BR PCPIntro (1), +.BR pmcd (1), +.BR pcp.conf (5) +and +.BR pcp.env (5). diff --git a/man/man1/pmdapapi.1 b/man/man1/pmdapapi.1 new file mode 100644 index 0000000..d1f2d63 --- /dev/null +++ b/man/man1/pmdapapi.1 @@ -0,0 +1,135 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2014 Red Hat. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.ds ia papi +.ds IA PAPI +.ds Ia Papi +.TH PMDAPAPI 1 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmdapapi\f1 \- \*(ia performance metrics domain agent (PMDA) +.SH SYNOPSIS +\f3$PCP_PMDAS_DIR/pmda\*(ia\f1 +[\f3\-d\f1 \f2domain\f1] +[\f3\-l\f1 \f2logfile\f1] +.SH DESCRIPTION +.B pmda\*(ia +is a \*(ia Performance Metrics Domain Agent (PMDA) which exposes +hardware performance counters via the library Performance API (Papi). +.PP +The metrics exported by the \*(ia PMDA report values gathered from +the hardware counters and metrics available, as reported by \*(ia. +Currently, only root users may access such metrics. +.PP +A brief description of the +.B pmda\*(ia +command line options follows: +.TP 5 +.B \-d +It is absolutely crucial that the performance metrics +.I domain +number specified here is unique and consistent. +That is, +.I domain +should be different for every PMDA on the one host, and the same +.I domain +number should be used for the same PMDA on all hosts. +.TP +.B \-l +Location of the log file. By default, a log file named +.I \*(ia.log +is written in the current directory of +.BR pmcd (1) +when +.B pmda\*(ia +is started, i.e. +.BR $PCP_LOG_DIR/pmcd . +If the log file cannot +be created or is not writable, output is written to the standard error instead. +.SH INSTALLATION +If you want access to the names, help text and values for the \*(ia +performance metrics, do the following as root: +.PP +.ft CW +.nf +.in +0.5i +# cd $PCP_PMDAS_DIR/\*(ia +# ./Install +.in +.fi +.ft 1 +.PP +If you want to undo the installation (and remove both PMDAs), +do the following as root: +.PP +.ft CW +.nf +.in +0.5i +# cd $PCP_PMDAS_DIR/\*(ia +# ./Remove +.in +.fi +.ft 1 +.PP +.B pmda\*(ia +is launched by +.BR pmcd (1) +and should never be executed directly. +The Install and Remove scripts notify +.BR pmcd (1) +when the agent is installed or removed. +.SH FILES +.PD 0 +.TP 10 +.B $PCP_PMCDCONF_PATH +command line options used to launch +.B pmda\*(ia +.TP 10 +.B $PCP_PMDAS_DIR/\*(ia/help +default help text file for the \*(ia metrics +.TP 10 +.B $PCP_PMDAS_DIR/\*(ia/Install +installation script for the +.B pmda\*(ia +agent +.TP 10 +.B $PCP_PMDAS_DIR/\*(ia/Remove +undo installation script for the +.B pmda\*(ia +agent +.TP 10 +.B $PCP_LOG_DIR/pmcd/sample.log +default log file for error messages and other information from +.B pmda\*(ia +.PD +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.B /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). +.SH SEE ALSO +.BR PCPIntro (1), +.BR pmcd (1), +.BR pcp.conf (5) +and +.BR pcp.env (5). diff --git a/man/man1/pmdaproc.1 b/man/man1/pmdaproc.1 new file mode 100644 index 0000000..191f178 --- /dev/null +++ b/man/man1/pmdaproc.1 @@ -0,0 +1,185 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2014 Red Hat. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.TH PMDAPROC 1 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmdaproc\f1 \- process performance metrics domain agent (PMDA) +.SH SYNOPSIS +\f3$PCP_PMDAS_DIR/proc/pmdaproc\f1 +[\f3\-AL\f1] +[\f3\-d\f1 \f2domain\f1] +[\f3\-l\f1 \f2logfile\f1] +[\f3\-r\f1 \f2cgroup\f1] +[\f3\-U\f1 \f2username\f1] +.SH DESCRIPTION +.B pmdaproc +is a Performance Metrics Domain Agent (PMDA) which extracts +performance metrics describing the state of the individual +processes running on a Linux system. +.PP +The +.B proc +PMDA exports metrics that measure the memory, processor and +other resource use of each process, as well as summary information +collated across all of the running processes. +The PMDA uses credentials passed from the +.BR PMAPI (3) +monitoring tool identifying the user requesting the information, +to ensure that only values the user is allowed to access are +returned by the PMDA. +This involves the PMDA temporarily changing its effective user and +group identifiers for the duration of requests for instances and +values. +In other words, system calls to extract information are performed +as the user originating the request and not as a privileged user. +The mechanisms available for transfer of user credentials are +described further in the +.BR PCPIntro (1) +page. +.PP +A brief description of the +.B pmdaproc +command line options follows: +.TP 5 +.B \-A +Disables use of the credentials provided by +.B PMAPI +client tools, +and simply runs everything under the "root" account. +.TP +.B \-L +Changes the per-process instance domain used by most +.B procproc +metrics to include threads as well. +.TP +.B \-d +It is absolutely crucial that the performance metrics +.I domain +number specified here is unique and consistent. +That is, +.I domain +should be different for every PMDA on the one host, and the same +.I domain +number should be used for the same PMDA on all hosts. +.TP +.B \-l +Location of the log file. By default, a log file named +.I proc.log +is written in the current directory of +.BR pmcd (1) +when +.B pmdaproc +is started, i.e. +.BR $PCP_LOG_DIR/pmcd . +If the log file cannot +be created or is not writable, output is written to the standard error instead. +.TP +.B \-r +Restrict the set of processes exported in the per-process instance domain +to only those processes that are contained by the specified +.IR cgroup +resource container. +This option provides an optional finer granularity to the monitoring, and +can also be used to reduce the resources consumed by +.I pmdaproc +during requests for instances and values. +.TP +.B \-U +User account under which to run the agent. +The default is the privileged "root" account, with +seteuid (2) +and +setegid (2) +switching for accessing most information. +.SH INSTALLATION +The +.B proc +PMDA is installed and available by default. +If you want to undo the installation, do the following as root: +.PP +.ft CW +.nf +.in +0.5i +# cd $PCP_PMDAS_DIR/proc +# ./Remove +.in +.fi +.ft 1 +.PP +If you want to establish access to the names, help text and values for the proc +performance metrics once more, after removal, do the following as root: +.PP +.ft CW +.nf +.in +0.5i +# cd $PCP_PMDAS_DIR/proc +# ./Install +.in +.fi +.ft 1 +.PP +.B pmdaproc +is launched by +.BR pmcd (1) +and should never be executed directly. +The Install and Remove scripts notify +.BR pmcd (1) +when the agent is installed or removed. +.SH FILES +.PD 0 +.TP 10 +.B $PCP_PMCDCONF_PATH +command line options used to launch +.B pmdaproc +.TP 10 +.B $PCP_PMDAS_DIR/proc/help +default help text file for the proc metrics +.TP 10 +.B $PCP_PMDAS_DIR/proc/Install +installation script for the +.B pmdaproc +agent +.TP 10 +.B $PCP_PMDAS_DIR/proc/Remove +undo installation script for the +.B pmdaproc +agent +.TP 10 +.B $PCP_LOG_DIR/pmcd/proc.log +default log file for error messages and other information from +.B pmdaproc +.PD +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.I /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). +.SH SEE ALSO +.BR PCPIntro (1), +.BR pmcd (1), +.BR seteuid (2), +.BR setegid (2), +.BR PMAPI (3), +.BR pcp.conf (5) +and +.BR pcp.env (5). diff --git a/man/man1/pmdaroomtemp.1 b/man/man1/pmdaroomtemp.1 new file mode 100644 index 0000000..468c66e --- /dev/null +++ b/man/man1/pmdaroomtemp.1 @@ -0,0 +1,136 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2014 Red Hat. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.TH PMDAROOMTEMP 1 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmdaroomtemp\f1 \- room temperature performance metrics domain agent (PMDA) +.SH SYNOPSIS +\f3$PCP_PMDAS_DIR/roomtemp/pmdaroomtemp\f1 +[\f3\-d\f1 \f2domain\f1] +[\f3\-l\f1 \f2logfile\f1] +.SH DESCRIPTION +.B pmdaroomtemp +is a Performance Metrics Domain Agent (PMDA) which exports the +temperature from one or more sensors built using the DS2480 and +DS1280 chipsets and MicroLAN technology from Dallas Semiconductor +Corporation. +.PP +The +.B roomtemp +PMDA exports metrics that reflect the temperatures from one or +more of these devices, in both degrees Celcius and Fahrenheit. +Each metric has one instance for each temperature sensor device. +The external instance identifiers are the serial numbers (in hex) +of the DS1280 chips discovered when the MicroLAN was probed. +.PP +A brief description of the +.B pmdaroomtemp +command line options follows: +.TP 5 +.B \-d +It is absolutely crucial that the performance metrics +.I domain +number specified here is unique and consistent. +That is, +.I domain +should be different for every PMDA on the one host, and the same +.I domain +number should be used for the same PMDA on all hosts. +.TP +.B \-l +Location of the log file. By default, a log file named +.I roomtemp.log +is written in the current directory of +.BR pmcd (1) +when +.B pmdaroomtemp +is started, i.e. +.BR $PCP_LOG_DIR/pmcd . +If the log file cannot +be created or is not writable, output is written to the standard error instead. +.SH INSTALLATION +If you want access to the names, help text and values for the roomtemp +performance metrics, do the following as root: +.PP +.ft CW +.nf +.in +0.5i +# cd $PCP_PMDAS_DIR/roomtemp +# ./Install +.in +.fi +.ft 1 +.PP +If you want to undo the installation, do the following as root: +.PP +.ft CW +.nf +.in +0.5i +# cd $PCP_PMDAS_DIR/roomtemp +# ./Remove +.in +.fi +.ft 1 +.PP +.B pmdaroomtemp +is launched by +.BR pmcd (1) +and should never be executed directly. +The Install and Remove scripts notify +.BR pmcd (1) +when the agent is installed or removed. +.SH FILES +.PD 0 +.TP 10 +.B $PCP_PMCDCONF_PATH +command line options used to launch +.B pmdaroomtemp +.TP 10 +.B $PCP_PMDAS_DIR/roomtemp/help +default help text file for the roomtemp metrics +.TP 10 +.B $PCP_PMDAS_DIR/roomtemp/Install +installation script for the +.B pmdaroomtemp +agent +.TP 10 +.B $PCP_PMDAS_DIR/roomtemp/Remove +undo installation script for the +.B pmdaroomtemp +agent +.TP 10 +.B $PCP_LOG_DIR/pmcd/roomtemp.log +default log file for error messages and other information from +.B pmdaroomtemp +.PD +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.I /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). +.SH SEE ALSO +.BR PCPIntro (1), +.BR pmcd (1), +.BR pcp.conf (5) +and +.BR pcp.env (5). diff --git a/man/man1/pmdarpm.1 b/man/man1/pmdarpm.1 new file mode 100644 index 0000000..48a02b5 --- /dev/null +++ b/man/man1/pmdarpm.1 @@ -0,0 +1,151 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2014 Red Hat. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.TH PMDARPM 1 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmdarpm\f1 \- RPM packages performance metrics domain agent (PMDA) +.SH SYNOPSIS +\f3$PCP_PMDAS_DIR/rpm/pmdarpm\f1 +[\f3\-C\f1] +[\f3\-d\f1 \f2domain\f1] +[\f3\-l\f1 \f2logfile\f1] +[\f3\-r\f1 \f2path\f1] +[\f3\-U\f1 \f2username\f1] +.SH DESCRIPTION +.B pmdarpm +is a Performance Metrics Domain Agent (PMDA) which extracts +performance metrics reflecting the state of the RPM package +database managed by +.BR rpm (1). +.PP +The +.B rpm +PMDA exports metrics that describe each package installed on a +system, as well as some cumulative totals. +When the RPM database changes the PMDA automatically detects this +and uses a background thread to asynchronously refresh its values. +.PP +A brief description of the +.B pmdarpm +command line options follows: +.TP 5 +.B \-C +Verify the package iteration code by scanning the RPM database +once, then exiting. +Only useful for problem diagnosis and testing. +.TP +.B \-d +It is absolutely crucial that the performance metrics +.I domain +number specified here is unique and consistent. +That is, +.I domain +should be different for every PMDA on the one host, and the same +.I domain +number should be used for the same PMDA on all hosts. +.TP +.B \-l +Location of the log file. By default, a log file named +.I rpm.log +is written in the current directory of +.BR pmcd (1) +when +.B pmdarpm +is started, i.e. +.BR $PCP_LOG_DIR/pmcd . +If the log file cannot +be created or is not writable, output is written to the standard error instead. +.TP +.B \-r +Specify an alternate path to the RPM database (default is +.IR /var/lib/rpm/Packages ). +.TP +.B \-U +User account under which to run the agent. +The default is the unprivileged "pcp" account. +.SH INSTALLATION +If you want access to the names, help text and values for the rpm +performance metrics, do the following as root: +.PP +.ft CW +.nf +.in +0.5i +# cd $PCP_PMDAS_DIR/rpm +# ./Install +.in +.fi +.ft 1 +.PP +If you want to undo the installation, do the following as root: +.PP +.ft CW +.nf +.in +0.5i +# cd $PCP_PMDAS_DIR/rpm +# ./Remove +.in +.fi +.ft 1 +.PP +.B pmdarpm +is launched by +.BR pmcd (1) +and should never be executed directly. +The Install and Remove scripts notify +.BR pmcd (1) +when the agent is installed or removed. +.SH FILES +.PD 0 +.TP 10 +.B $PCP_PMCDCONF_PATH +command line options used to launch +.B pmdarpm +.TP 10 +.B $PCP_PMDAS_DIR/rpm/help +default help text file for the rpm metrics +.TP 10 +.B $PCP_PMDAS_DIR/rpm/Install +installation script for the +.B pmdarpm +agent +.TP 10 +.B $PCP_PMDAS_DIR/rpm/Remove +undo installation script for the +.B pmdarpm +agent +.TP 10 +.B $PCP_LOG_DIR/pmcd/rpm.log +default log file for error messages and other information from +.B pmdarpm +.PD +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.I /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). +.SH SEE ALSO +.BR PCPIntro (1), +.BR pmcd (1), +.BR pcp.conf (5) +and +.BR pcp.env (5). diff --git a/man/man1/pmdasample.1 b/man/man1/pmdasample.1 new file mode 100644 index 0000000..296740d --- /dev/null +++ b/man/man1/pmdasample.1 @@ -0,0 +1,186 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2012 Red Hat. +.\" Copyright (c) 2000 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.\" I am variants ... +.ds ia sample +.ds IA SAMPLE +.ds Ia Sample +.TH PMDASAMPLE 1 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmdasample\f1 \- \*(ia performance metrics domain agent (PMDA) +.SH SYNOPSIS +\f3$PCP_PMDAS_DIR/pmda\*(ia\f1 +[\f3\-d\f1 \f2domain\f1] +[\f3\-i\f1 \f2port\f1] +[\f3\-l\f1 \f2logfile\f1] +[\f3\-p\f1] +[\f3\-u\f1 \f2socket\f1] +[\f3\-U\f1 \f2username\f1] +.SH DESCRIPTION +.B pmda\*(ia +is a \*(ia Performance Metrics Domain Agent (PMDA) which exports +a variety of synthetic performance metrics. +.PP +This PMDA was developed as part of the quality assurance testing +for the PCP product, but has other uses, most notably in the +development of new PCP clients. +.PP +The metrics exported by the \*(ia PMDA cover the full range of +data types, data semantics, value cardinality, instance domain +stability and error conditions found in real PMDAs. +.PP +A brief description of the +.B pmda\*(ia +command line options follows: +.TP 5 +.B \-d +It is absolutely crucial that the performance metrics +.I domain +number specified here is unique and consistent. +That is, +.I domain +should be different for every PMDA on the one host, and the same +.I domain +number should be used for the same PMDA on all hosts. +.TP +.B \-i +Expect PMCD to connect to +.B pmda\*(ia +on the specified TCP/IP port. +.I port +may be a port number or port name. +.TP +.B \-l +Location of the log file. By default, a log file named +.I \*(ia.log +is written in the current directory of +.BR pmcd (1) +when +.B pmda\*(ia +is started, i.e. +.BR $PCP_LOG_DIR/pmcd . +If the log file cannot +be created or is not writable, output is written to the standard error instead. +.TP +.B \-p +Expect PMCD to create a pipe and the connection to +.B pmda\*(ia +is via standard input and standard output. This is the +default connection mode. +.TP +.B \-u +Expect PMCD to connect to +.B pmda\*(ia +on the Unix domain socket named +.IR socket . +.TP 5 +.B \-U +User account under which to run the agent. +The default is the unprivileged "pcp" account in current versions of PCP, +but in older versions the superuser account ("root") was used by default. +.PP +At most one of the options +.BR \-i , +.B \-p +and +.B \-u +may be specified. +.SH INSTALLATION +If you want access to the names, help text and values for the \*(ia +performance metrics, do the following as root: +.PP +.ft CW +.nf +.in +0.5i +# cd $PCP_PMDAS_DIR/\*(ia +# ./Install +.in +.fi +.ft 1 +.PP +Note that the installation script also installs the DSO version of +the \*(ia PMDA, so there are in fact two PMDAs installed, and two +sets of performance metrics, namely +.B sample.* +and +.BR sampledso.* . +.PP +If you want to undo the installation (and remove both PMDAs), +do the following as root: +.PP +.ft CW +.nf +.in +0.5i +# cd $PCP_PMDAS_DIR/\*(ia +# ./Remove +.in +.fi +.ft 1 +.PP +.B pmda\*(ia +is launched by +.BR pmcd (1) +and should never be executed directly. +The Install and Remove scripts notify +.BR pmcd (1) +when the agent is installed or removed. +.SH FILES +.PD 0 +.TP 10 +.B $PCP_PMCDCONF_PATH +command line options used to launch +.B pmda\*(ia +.TP 10 +.B $PCP_PMDAS_DIR/\*(ia/help +default help text file for the \*(ia metrics +.TP 10 +.B $PCP_PMDAS_DIR/\*(ia/Install +installation script for the +.B pmda\*(ia +agent +.TP 10 +.B $PCP_PMDAS_DIR/\*(ia/Remove +undo installation script for the +.B pmda\*(ia +agent +.TP 10 +.B $PCP_LOG_DIR/pmcd/sample.log +default log file for error messages and other information from +.B pmda\*(ia +.PD +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.B /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). +.SH SEE ALSO +.BR PCPIntro (1), +.BR pmcd (1), +.BR pmdasimple (1), +.BR pmdatrivial (1), +.BR pmdatxmon (1), +.BR pcp.conf (5) +and +.BR pcp.env (5). diff --git a/man/man1/pmdasendmail.1 b/man/man1/pmdasendmail.1 new file mode 100644 index 0000000..7e5406b --- /dev/null +++ b/man/man1/pmdasendmail.1 @@ -0,0 +1,160 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2012 Red Hat. +.\" Copyright (c) 2000 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.\" I am variants ... +.ds ia sendmail +.ds IA SENDMAIL +.ds Ia Sendmail +.TH PMDASENDMAIL 1 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmdasendmail\f1 \- \*(ia performance metrics domain agent (PMDA) +.SH SYNOPSIS +\f3$PCP_PMDAS_DIR/\*(ia/pmda\*(ia\f1 +[\f3\-d\f1 \f2domain\f1] +[\f3\-l\f1 \f2logfile\f1] +[\f3\-U\f1 \f2username\f1] +.SH DESCRIPTION +.B pmda\*(ia +is a \*(ia Performance Metrics Domain Agent (PMDA) which exports +mail traffic statistics as collected by +.BR sendmail (1). +.PP +Before the \*(ia PMDA can export any metrics, +.BR sendmail (1) +must have statistics collection enabled. This involves checking the +name of the statistics file, as given by the +.B OS +or +.B "O StatusFile" +control lines in +.BR /etc/sendmail.cf , +and then creating this file if it does not already exist. +Removing the file will terminate statistics collection by +.BR sendmail (1) +and hence the \*(ia PMDA. +.PP +A brief description of the +.B pmda\*(ia +command line options follows: +.TP 5 +.B \-d +It is absolutely crucial that the performance metrics +.I domain +number specified here is unique and consistent. +That is, +.I domain +should be different for every PMDA on the one host, and the same +.I domain +number should be used for the same PMDA on all hosts. +.TP +.B \-l +Location of the log file. By default, a log file named +.I \*(ia.log +is written in the current directory of +.BR pmcd (1) +when +.B pmda\*(ia +is started, i.e. +.BR $PCP_LOG_DIR/pmcd . +If the log file cannot +be created or is not writable, output is written to the standard error instead. +.TP 5 +.B \-U +User account under which to run the agent. +The default is the unprivileged "pcp" account in current versions of PCP, +but in older versions the superuser account ("root") was used by default. +.PP +There are no communication options, as the +.I Install +script ensures the \*(ia PMDA will be connected to +PMCD by a pipe. +.SH INSTALLATION +If you want access to the names, help text and values for the \*(ia +performance metrics, do the following as root: +.PP +.ft CW +.nf +.in +0.5i +# cd $PCP_PMDAS_DIR/\*(ia +# ./Install +.in +.fi +.ft 1 +.PP +If you want to undo the installation, do the following as root: +.PP +.ft CW +.nf +.in +0.5i +# cd $PCP_PMDAS_DIR/\*(ia +# ./Remove +.in +.fi +.ft 1 +.PP +.B pmda\*(ia +is launched by +.BR pmcd (1) +and should never be executed directly. +The Install and Remove scripts notify +.BR pmcd (1) +when the agent is installed or removed. +.SH FILES +.PD 0 +.TP 10 +.B $PCP_PMCDCONF_PATH +command line options used to launch +.B pmda\*(ia +.TP +.B $PCP_PMDAS_DIR/\*(ia/help +default help text file for the \*(ia metrics +.TP +.B $PCP_PMDAS_DIR/\*(ia/Install +installation script for the +.B pmda\*(ia +agent +.TP +.B $PCP_PMDAS_DIR/\*(ia/Remove +undo installation script for the +.B pmda\*(ia +agent +.TP +.B $PCP_LOG_DIR/pmcd/\*(ia.log +default log file for error messages and other information from +.B pmda\*(ia +.TP +.B /etc/sendmail.cf +.B sendmail +configuration file to identify the name of the statistics file +.PD +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.B /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). +.SH SEE ALSO +.BR pmcd (1) +and +.BR sendmail (1). diff --git a/man/man1/pmdashping.1 b/man/man1/pmdashping.1 new file mode 100644 index 0000000..5a03d90 --- /dev/null +++ b/man/man1/pmdashping.1 @@ -0,0 +1,214 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2012 Red Hat. +.\" Copyright (c) 2000-2004 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMDASHPING 1 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmdashping\f1 \- "shell-ping" performance metrics domain agent +.SH SYNOPSIS +\f3$PCP_PMDAS_DIR/shping/pmdashping\f1 +[\f3\-C\f1] +[\f3\-d\f1 \f2domain\f1] +[\f3\-l\f1 \f2logfile\f1] +[\f3\-I\f1 \f2interval\f1] +[\f3\-t\f1 \f2timeout\f1] +[\f3\-U\f1 \f2username\f1] +\f2configfile\f1 +.br +.SH DESCRIPTION +.B pmdashping +is a Performance Metrics Domain Agent (PMDA) which exports +quality of service and response time measurements for +arbitrary commands as might be run from a shell such as +.BR sh (1). +.PP +These measurements are intended to be used to quantify service +quality and service availability for those services that are +either mission critical or act as early indicators of adverse +system performance. +.PP +The sample configuration monitors +simple shell commands (\c +.B exit +and +.BR date (1)), +a short computationally intensive task +using +.BR sum (1), +a short C compilation, +DNS lookup via +.BR nslookup (1), +YP lookup via +.BR ypcat (1), +bind/portmapper service using +.BR rpcbind (1), +SMTP by connecting to telnet port 25 and sending an ``expn root'' +request, +and +NNTP by connecting to telnet port 119 and running a ``listgroup'' +command. +.PP +It is expected that other commands would follow the examples in the +sample configuration file, and most deployments of the +.B pmdashping +PMDA are expected to use a customized configuration file. +.PP +A brief description of the +.B pmdashping +command line options follows: +.TP 5 +.B \-C +Parse +.IR configfile , +reporting any errors and exiting with non-zero status if the file contains +syntactical errors. +.TP 5 +.B \-d +It is absolutely crucial that the performance metrics +.I domain +number specified here is unique and consistent. +That is, +.I domain +should be different for every PMDA on the one host, and the same +.I domain +number should be used for the same PMDA on all hosts. +.TP 5 +.B \-l +Location of the log file. By default, a log file named +.I shping.log +is written in the current directory of +.BR pmcd (1) +when +.B pmdashping +is started, i.e. +.BR $PCP_LOG_DIR/pmcd . +If the log file cannot +be created or is not writable, output is written to the standard error instead. +.TP 5 +.B \-I +Amount of time (in seconds) between subsequent executions of the list of +commands provided via the configuration file +.IR configfile . +The default is 2 minutes. +.TP 5 +.B \-t +Amount of time (in seconds) to wait before timing out awaiting a response +for a command from +.IR configfile . +The default is 20 seconds. +.TP 5 +.B \-U +User account under which to run the agent and all commands. +The default is the unprivileged "pcp" account in current versions of PCP, +but in older versions the superuser account ("root") was used by default. +.PP +The required +.IR configfile +specifies ``tag'' and ``command'' pairs, each on a separate line. +All of the commands are run one after another, with the whole +group rescheduled to be run once per +.IR interval . +For each command that is run, +.B pmdashping +records information related to the success (or timeout), +exit status, elapsed time and CPU time +(system and user), and this information is exported by the PMDA. +The tags are used to identify the individual commands amongst the values +exported by the PMDA, and form the external instance domain identifiers +for the +.B pmdashping +metrics which relate to each command. +.PP +.SH INSTALLATION +In order for a host to export the names, help text and values for the shping +performance metrics, do the following as root: +.PP +.ft CW +.nf +.in +0.5i +# cd $PCP_PMDAS_DIR/shping +# ./Install +.in +.fi +.ft 1 +.PP +The set of ``tag'' and ``command'' pairs may be specified from +a default (sample) configuration file, a customized file or entered +interactively as part of the +.B Install +script. +.PP +If you want to undo the installation, do the following as root: +.PP +.ft CW +.nf +.in +0.5i +# cd $PCP_PMDAS_DIR/shping +# ./Remove +.in +.fi +.ft 1 +.PP +.B pmdashping +is launched by +.BR pmcd (1) +and should never be executed directly. +The Install and Remove scripts notify +.BR pmcd (1) +when the agent is installed or removed. +.SH FILES +.PD 0 +.TP 10 +.B $PCP_PMCDCONF_PATH +command line options used to launch +.B pmdashping +.TP 10 +.B $PCP_PMDAS_DIR/shping/help +default help text file for the shping metrics +.TP 10 +.B $PCP_PMDAS_DIR/shping/sample.conf +example configuration file with a number of common commands +.TP 10 +.B $PCP_PMDAS_DIR/shping/Install +installation script for the +.B pmdashping +agent +.TP 10 +.B $PCP_PMDAS_DIR/shping/Remove +undo installation script for +.B pmdashping +.TP 10 +.B $PCP_LOG_DIR/pmcd/shping.log +default log file for error messages and other information from +.B pmdashping +.PD +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.B /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). +.SH SEE ALSO +.BR pmcd (1) +and +.BR pmgshping (1). diff --git a/man/man1/pmdasimple.1 b/man/man1/pmdasimple.1 new file mode 100644 index 0000000..280fe1e --- /dev/null +++ b/man/man1/pmdasimple.1 @@ -0,0 +1,198 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2012 Red Hat. +.\" Copyright (c) 2000 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.\" I am variants ... +.ds ia simple +.ds IA SIMPLE +.ds Ia Simple +.TH PMDASIMPLE 1 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmdasimple\f1 \- \*(ia performance metrics domain agent (PMDA) +.SH SYNOPSIS +\f3$PCP_PMDAS_DIR/\*(ia/pmda\*(ia\f1 +[\f3\-d\f1 \f2domain\f1] +[\f3\-i\f1 \f2port\f1] +[\f3\-l\f1 \f2logfile\f1] +[\f3\-p\f1] +[\f3\-u\f1 \f2socket\f1] +[\f3\-U\f1 \f2username\f1] +.SH DESCRIPTION +.B pmda\*(ia +is a \*(ia Performance Metrics Domain Agent (PMDA) which exports +a small number of synthetic performance metrics. +.PP +The \*(ia PMDA is +shipped as source code and is designed to be an aid for PMDA developers. +In terms of code size and features, it is more complex than the +trivial PMDA, about the same as the txmon PMDA +and less complex than the sample PMDA. +The source for the \*(ia PMDA is a good template from which production, +customized PMDAs can be developed. +.PP +A brief description of the +.B pmda\*(ia +command line options follows: +.TP 5 +.B \-d +It is absolutely crucial that the performance metrics +.I domain +number specified here is unique and consistent. +That is, +.I domain +should be different for every PMDA on the one host, and the same +.I domain +number should be used for the same PMDA on all hosts. +.TP +.B \-i +Expect PMCD to connect to +.B pmda\*(ia +on the specified TCP/IP port. +.I port +may be a port number or port name. +.TP +.B \-l +Location of the log file. By default, a log file named +.I \*(ia.log +is written in the current directory of +.BR pmcd (1) +when +.B pmda\*(ia +is started, i.e. +.BR $PCP_LOG_DIR/pmcd . +If the log file cannot +be created or is not writable, output is written to the standard error instead. +.TP +.B \-p +Expect PMCD to create a pipe and the connection to +.B pmda\*(ia +is via standard input and standard output. This is the +default connection mode. +.TP +.B \-u +Expect PMCD to connect to +.B pmda\*(ia +on the Unix domain socket named +.IR socket . +.TP 5 +.B \-U +User account under which to run the agent. +The default is the unprivileged "pcp" account in current versions of PCP, +but in older versions the superuser account ("root") was used by default. +.PP +At most one of the options +.BR \-i , +.B \-p +and +.B \-u +may be specified. +.SH INSTALLATION +If you want access the names, help text and values for the \*(ia +performance metrics, do the following as root: +.PP +.ft CW +.nf +.in +0.5i +# cd $PCP_PMDAS_DIR/\*(ia +# ./Install +.in +.fi +.ft 1 +.PP +If you want to undo the installation, do the following as root: +.PP +.ft CW +.nf +.in +0.5i +# cd $PCP_PMDAS_DIR/\*(ia +# ./Remove +.in +.fi +.ft 1 +.PP +.B pmda\*(ia +is launched by +.BR pmcd (1) +and should never be executed directly. +The Install and Remove scripts notify +.BR pmcd (1) +when the agent is installed or removed. +.SH FILES +.PD 0 +.TP 10 +.B $PCP_PMCDCONF_PATH +command line options used to launch +.B pmda\*(ia +.TP +.B $PCP_PMDAS_DIR/\*(ia/help +default help text file for the \*(ia metrics +.TP +.B $PCP_PMDAS_DIR/\*(ia/Install +installation script for the +.B pmda\*(ia +agent +.TP +.B $PCP_PMDAS_DIR/\*(ia/Remove +undo installation script for the +.B pmda\*(ia +agent +.TP +.B $PCP_PMDAS_DIR/\*(ia/simple.conf +configuration file for the dynamic instance domain that +underlies the +.B simple.now +performance metric. For a description, refer to the +help text file, or run the command +.sp 0.5v +.ft CW +$ pminfo \-T simple.now +.ft P +.sp 0.5v +.TP +.B $PCP_PMDAS_DIR/\*(ia/*.pmda_simple.so +The DSO version of the PMDA. The same source is used to create both the +DSO and the daemon versions of the \*(ia PMDA, and one or the other +may be installed as part of the dialog in the +.B Install +script. +.TP +.B $PCP_LOG_DIR/pmcd/simple.log +default log file for error messages and other information from +.B pmda\*(ia +.PD +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.B /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). +.SH SEE ALSO +.BR PCPIntro (1), +.BR pmcd (1), +.BR pmdasample (1), +.BR pmdatrivial (1), +.BR pmdatxmon (1), +.BR PMDA (3), +.BR pcp.conf (5) +and +.BR pcp.env (5). diff --git a/man/man1/pmdasummary.1 b/man/man1/pmdasummary.1 new file mode 100644 index 0000000..100b4dd --- /dev/null +++ b/man/man1/pmdasummary.1 @@ -0,0 +1,147 @@ +'\"macro stdmacro +.TH PMDASUMMARY 1 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmdasummary\f1 \- summary performance metrics domain agent (PMDA) +.SH SYNOPSIS +\f3$PCP_PMDAS_DIR/summary/pmdasummary\f1 +[\f3\-d\f1 \f2domain\f1] +[\f3\-h\f1 \f2helpfile\f1] +[\f3\-l\f1 \f2logfile\f1] +[\f3\-U\f1 \f2username\f1] +\f2pmie-command-line\f1 +.SH DESCRIPTION +.B pmdasummary +is a Performance Metrics Domain Agent (PMDA) which derives +performance metrics values from values made available by other PMDAs. +.B pmdasummary +consists of two processes: +.TP +.B pmie process +The inference engine for performance values +.BR pmie (1) +is used to periodically sample values for the base metrics and compute +the derived values. +This process is launched with the given \f2pmie-command-line\f1 arguments +by the main process, described below. +.TP +.B main process +The main process reads and buffers the values computed by +.BR pmie (1) +and makes them available to the performance metrics collector daemon +.BR pmcd (1). +.PP +A brief description of the +.B pmdasummary +command line options follows: +.TP 5 +.B \-d +It is absolutely crucial that the performance metrics +.I domain +number specified here is unique and consistent. +That is, +.I domain +should be different for every PMDA on the one host, and the same +.I domain +number should be used for the same PMDA on all hosts. +.TP 5 +.B \-h +This option specifies an alternative help text file +.I helpfile +for describing the metrics that +.B pmdasummary +represents. +.TP 5 +.B \-l +Location of the log file. By default, a log file named +.I summary.log +is written in the current directory of +.BR pmcd (1) +when +.B pmdasummary +is started, i.e. +.BR $PCP_LOG_DIR/pmcd . +If the log file cannot +be created or is not writable, output is written to the standard error instead. +.TP 5 +.B \-U +User account under which to run the agent. +The default is the unprivileged "pcp" account in current versions of PCP, +but in older versions the superuser account ("root") was used by default. +.SH INSTALLATION +If you want access to the names, help text and values for the summary +performance metrics, do the following as root: +.PP +.ft CW +.nf +.in +0.5i +# cd $PCP_PMDAS_DIR/summary +# ./Install +.in +.fi +.ft 1 +.PP +If you want to undo the installation, do the following as root: +.PP +.ft CW +.nf +.in +0.5i +# cd $PCP_PMDAS_DIR/summary +# ./Remove +.in +.fi +.ft 1 +.PP +.B pmdasummary +is launched by +.BR pmcd (1) +and should never be executed directly. +The Install and Remove scripts notify +.BR pmcd (1) +when the agent is installed or removed. +.SH FILES +.PD 0 +.TP 10 +.B $PCP_PMCDCONF_PATH +command line options used to launch +.B pmdasummary +.TP 10 +.B $PCP_PMDAS_DIR/summary/expr.pmie +default +.BR pmie (1) +expressions defining the summary metrics +.TP 10 +.B $PCP_PMDAS_DIR/summary/help +default help text for the summary metrics +.TP 10 +.B $PCP_PMDAS_DIR/summary/Install +installation script for the +.B pmdasummary +agent +.TP 10 +.B $PCP_PMDAS_DIR/summary/Remove +undo installation script for the +.B pmdasummary +agent +.TP 10 +.B $PCP_LOG_DIR/pmcd/summary.log +default log file for error messages and other information from +.B pmdasummary +.PD +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.B /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). +.SH SEE ALSO +.BR pmcd (1) +and +.BR pmie (1). diff --git a/man/man1/pmdasystemd.1 b/man/man1/pmdasystemd.1 new file mode 100644 index 0000000..b4fd3bd --- /dev/null +++ b/man/man1/pmdasystemd.1 @@ -0,0 +1,176 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2014 Red Hat. +.\" Copyright (c) 2000 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.TH PMDASYSTEMD 1 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmdasystemd\f1 \- systemd performance metrics domain agent (PMDA) +.SH SYNOPSIS +\f3$PCP_PMDAS_DIR/systemd/pmdasystemd\f1 +[\f3\-f\f1] +[\f3\-d\f1 \f2domain\f1] +[\f3\-l\f1 \f2logfile\f1] +[\f3\-m\f1 \f2memory\f1] +[\f3\-s\f1 \f2interval\f1] +[\f3\-U\f1 \f2username\f1] +.SH DESCRIPTION +.B pmdasystemd +is a systemd log file monitoring Performance Metrics Domain +Agent (PMDA). +It can be seen as analagous to the +.B \-f +option to +.BR journalctl (1) +and converts each new log line into a performance event, +suitable for consumption by +.BR PMAPI (3) +client tools like +.BR pmevent (1). +.PP +The +.B systemd +PMDA exports both event-style metrics reflecting timestamped event +records for messages logged to the system logs, as well as the more +orthodox sample-style metrics such as message counts and throughput +size values. +.PP +A brief description of the +.B pmdasystemd +command line options follows: +.TP 5 +.B \-d +It is absolutely crucial that the performance metrics +.I domain +number specified here is unique and consistent. +That is, +.I domain +should be different for every PMDA on the one host, and the same +.I domain +number should be used for the same PMDA on all hosts. +.TP +.B \-f +Disables per-uid/gid record filtering. +By default the user and group credentials will be used to +filter log records returned to the client tool, preventing +information exposure to arbitrary users. +This option disables that, so use only with extreme caution. +.TP +.B \-l +Location of the log file. By default, a log file named +.I systemd.log +is written in the current directory of +.BR pmcd (1) +when +.B pmdasystemd +is started, i.e. +.BR $PCP_LOG_DIR/pmcd . +If the log file cannot +be created or is not writable, output is written to the standard error instead. +.TP +.B \-m +Limit the physical memory used by the PMDA to buffer event records to +.I maxsize +bytes. +As log events arrive at the PMDA, they must be buffered until individual +client tools request the next batch since their previous batch of events. +The default maximum is 2 megabytes. +.TP +.B \-s +Sets the polling interval for detecting newly arrived log lines. +Mirrors the same option from the +.BR tail (1) +command. +.TP +.B \-U +User account under which to run the agent. +The default is the "adm" user account. +.SH INSTALLATION +If you want access to the names, help text and values for the systemd +performance metrics, do the following as root: +.PP +.ft CW +.nf +.in +0.5i +# cd $PCP_PMDAS_DIR/systemd +# ./Install +.in +.fi +.ft 1 +.PP +If you want to undo the installation, do the following as root: +.PP +.ft CW +.nf +.in +0.5i +# cd $PCP_PMDAS_DIR/systemd +# ./Remove +.in +.fi +.ft 1 +.PP +.B pmdasystemd +is launched by +.BR pmcd (1) +and should never be executed directly. +The Install and Remove scripts notify +.BR pmcd (1) +when the agent is installed or removed. +.SH FILES +.PD 0 +.TP 10 +.B $PCP_PMCDCONF_PATH +command line options used to launch +.B pmdasystemd +.TP 10 +.B $PCP_PMDAS_DIR/systemd/help +default help text file for the systemd metrics +.TP 10 +.B $PCP_PMDAS_DIR/systemd/Install +installation script for the +.B pmdasystemd +agent +.TP 10 +.B $PCP_PMDAS_DIR/systemd/Remove +undo installation script for the +.B pmdasystemd +agent +.TP 10 +.B $PCP_LOG_DIR/pmcd/systemd.log +default log file for error messages and other information from +.B pmdasystemd +.PD +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.I /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). +.SH SEE ALSO +.BR PCPIntro (1), +.BR pmcd (1), +.BR pmevent (1), +.BR journalctl (1), +.BR tail (1), +.BR PMAPI (3), +.BR pcp.conf (5) +and +.BR pcp.env (5). diff --git a/man/man1/pmdate.1 b/man/man1/pmdate.1 new file mode 100644 index 0000000..2e0465d --- /dev/null +++ b/man/man1/pmdate.1 @@ -0,0 +1,80 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMDATE 1 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmdate\f1 \- display an offset date +.\" literals use .B or \f3 +.\" arguments use .I or \f2 +.SH SYNOPSIS +.B pmdate +[ \fIoffset\fR ... ] +.I format +.SH DESCRIPTION +.B pmdate +displays the current date and/or time, with an optional offset. +.PP +An +.I offset +is specified with a leading sign (``+'' or ``-''), followed by an +integer value, followed by one of the following ``scale'' specifiers; +.IP S +seconds +.PD 0 +.IP M +minutes +.IP H +hours +.IP d +days +.IP m +months +.IP y +years +.PD +.PP +The output +.I format +follows the same rules as for +.BR date (1) +and +.BR strftime (3). +.PP +For example, the following will display the date a week ago as DDMMYYYY; +.in +8n +.ft CW +pmdate \-7d %d%m%Y +.ft R +.in -8n +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.I /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). +.SH SEE ALSO +.BR date (1), +.BR strftime (3), +.BR pcp.conf (5) +and +.BR pcp.env (5). diff --git a/man/man1/pmdatrace.1 b/man/man1/pmdatrace.1 new file mode 100644 index 0000000..353e8d6 --- /dev/null +++ b/man/man1/pmdatrace.1 @@ -0,0 +1,217 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2012 Red Hat. +.\" Copyright (c) 2000 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMDATRACE 1 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmdatrace\f1 \- application-level transaction performance metrics domain agent +.SH SYNOPSIS +\f3$PCP_PMDAS_DIR/trace/pmdatrace\f1 +[\f3\-d\f1 \f2domain\f1] +[\f3\-l\f1 \f2logfile\f1] +[\f3\-A\f1 \f2access\f1] +[\f3\-I\f1 \f2port\f1] +[\f3\-M\f1 \f2username\f1] +[\f3\-N\f1 \f2buckets\f1] +[\f3\-T\f1 \f2period\f1] +[\f3\-U\f1 \f2units\f1] +.br +.SH DESCRIPTION +.B pmdatrace +is a Performance Metrics Domain Agent (PMDA) which exports transaction +performance metrics from application processes which use the +.I pcp_trace +library described in +.BR pmdatrace (3). +.PP +A brief description of the +.B pmdatrace +command line options follows: +.TP 5 +.B \-d +It is absolutely crucial that the performance metrics +.I domain +number specified here is unique and consistent. +That is, +.I domain +should be different for every PMDA on the one host, and the same +.I domain +number should be used for the same PMDA on all hosts. +.TP 5 +.B \-l +Location of the log file. By default, a log file named +.I trace.log +is written in the current directory of +.BR pmcd (1) +when +.B pmdatrace +is started, i.e. +.BR $PCP_LOG_DIR/pmcd . +If the log file cannot +be created or is not writable, output is written to the standard error instead. +.TP 5 +.B \-A +Host-based access control for +.BR pmdatrace . +.I access +must be either an allow or deny specification, using either +allow:hostspec:maxconns or disallow:hostspec, where `allow' and `disallow' are +keywords, `hostspec' is a host specification conforming to the format used by +both +.BR pmcd (1) +and +.BR pmlogger (1), +and `maxconns' is the maximum number of connections allowed from a given +`hostspec'. +Using a maximum connections of zero specifies an unlimited number of +connections for the accompanying `hostspec'. +.TP 5 +.B \-I +Communicate with +.I pcp_trace +clients via the given Internet +.IR port . +This can alternatively be specified by setting +.B $PCP_TRACE_PORT +in the environment to some valid port number (use of the +.B \-I +option overrides this). +The default port number is 4323. +.TP 5 +.B \-T +\f2period\f1 defines the aggregation period used to compute the recent +averages and extrema. +Specified as a time interval using the syntax described in +.BR PCPIntro (1) +for the common +.B \-t +PCP argument, e.g. \c +.B "30 seconds" +or +.BR "1 min" . +The default is 60 seconds. +.TP 5 +.B \-M +User account under which to run the agent. +The default is the unprivileged "pcp" account in current versions of PCP, +but in older versions the superuser account ("root") was used by default. +.TP 5 +.B \-N +Internally, the aggregation \f2period\f1 is divided into \f2bucket\f1 +divisions, and the rolling average is recomputed every +\f2period\f1/\f2bucket\f1 seconds. +For example, the defaults correspond to \-T 60 and \-N 12, which means +the average is recomputed every five seconds for a period covering the +prior 60 seconds. +.TP 5 +.B \-U +This option allows the dimension and scale associated with the observation +value metric to be configured. +\f2units\f1 is a comma-separated string of six integer values, which are the +space dimension, time dimension, count dimension, space scale, time scale, and +count scale, respectively. +The default dimension and scale is ``none'', which is equivalent to +presenting ``0,0,0,0,0,0'' as the argument to \-U. +The units associated with a metric are most easily viewed using the \-d +(metric description) option to +.BR pminfo (1). +The Install script described below steps through this option quite explicitly, +so it is recommended that the Install script be used for building up the +\f2units\f1 specification. +.PP +Essentially, the exported metrics provide statistics on the time for +completion of each transaction, and an average count of transactions completed +and watch points passed over a given time \f2period\f1. +.PP +.SH INSTALLATION +In order for a host to export the names, help text and values for the Trace +performance metrics, do the following as root: +.PP +.ft CW +.nf +.in +0.5i +# cd $PCP_PMDAS_DIR/trace +# ./Install +.in +.fi +.ft 1 +.PP +If you want to undo the installation, do the following as root: +.PP +.ft CW +.nf +.in +0.5i +# cd $PCP_PMDAS_DIR/trace +# ./Remove +.in +.fi +.ft 1 +.PP +.B pmdatrace +is launched by +.BR pmcd (1) +and should never be executed directly. +The Install and Remove scripts notify +.BR pmcd (1) +when the agent is installed or removed. +.SH FILES +.PD 0 +.TP 10 +.B $PCP_PMCDCONF_PATH +command line options used to launch +.B pmdatrace +.TP 10 +.B $PCP_PMDAS_DIR/trace/help +default help text file for the trace metrics +.TP 10 +.B $PCP_DEMOS_DIR/trace/* +example programs which use the +.I pcp_trace +library +.TP 10 +.B $PCP_PMDAS_DIR/trace/Install +installation script for the +.B pmdatrace +agent +.TP 10 +.B $PCP_PMDAS_DIR/trace/Remove +undo installation script for +.B pmdatrace +.TP 10 +.B $PCP_LOG_DIR/pmcd/trace.log +default log file for error messages and other information from +.B pmdatrace +.PD +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.B /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). +.SH SEE ALSO +.BR PCPIntro (1), +.BR pmcd (1), +.BR pmtrace (1), +.BR PMAPI (3) +and +.BR pmdatrace (3). diff --git a/man/man1/pmdatrivial.1 b/man/man1/pmdatrivial.1 new file mode 100644 index 0000000..33eec9b --- /dev/null +++ b/man/man1/pmdatrivial.1 @@ -0,0 +1,144 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2012 Red Hat. +.\" Copyright (c) 2000 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.\" I am variants ... +.ds ia trivial +.ds IA TRIVIAL +.ds Ia Trivial +.TH PMDATRIVIAL 1 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmdatrivial\f1 \- \*(ia performance metrics domain agent (PMDA) +.SH SYNOPSIS +\f3$PCP_PMDAS_DIR/\*(ia/pmda\*(ia\f1 +[\f3\-d\f1 \f2domain\f1] +[\f3\-l\f1 \f2logfile\f1] +[\f3\-U\f1 \f2username\f1] +.SH DESCRIPTION +.B pmda\*(ia +is the simplest possible Performance Metrics Domain Agent (PMDA) which +exports a single performance metric, the time +in seconds since the 1st of January, 1970. +.PP +The \*(ia PMDA is +shipped as source code and is designed to be an aid for PMDA developers. +.PP +A brief description of the +.B pmda\*(ia +command line options follows: +.TP 5 +.B \-d +It is absolutely crucial that the performance metrics +.I domain +number specified here is unique and consistent. +That is, +.I domain +should be different for every PMDA on the one host, and the same +.I domain +number should be used for the same PMDA on all hosts. +.TP +.B \-l +Location of the log file. By default, a log file named +.I \*(ia.log +is written in the current directory of +.BR pmcd (1) +when +.B pmda\*(ia +is started, i.e. +.BR $PCP_LOG_DIR/pmcd . +If the log file cannot +be created or is not writable, output is written to the standard error instead. +.TP 5 +.B \-U +User account under which to run the agent. +The default is the unprivileged "pcp" account in current versions of PCP, +but in older versions the superuser account ("root") was used by default. +.SH INSTALLATION +If you want access to the names, help text and values for the \*(ia +performance metrics, do the following as root: +.PP +.ft CW +.nf +.in +0.5i +# cd $PCP_PMDAS_DIR/\*(ia +# ./Install +.in +.fi +.ft 1 +.PP +If you want to undo the installation, do the following as root: +.PP +.ft CW +.nf +.in +0.5i +# cd $PCP_PMDAS_DIR/\*(ia +# ./Remove +.in +.fi +.ft 1 +.PP +.B pmda\*(ia +is launched by +.BR pmcd (1) +and should never be executed directly. +The Install and Remove scripts notify +.BR pmcd (1) +when the agent is installed or removed. +.SH FILES +.PD 0 +.TP 10 +.B $PCP_PMCDCONF_PATH +command line options used to launch +.B pmda\*(ia +.TP 10 +.B $PCP_PMDAS_DIR/\*(ia/help +default help text file for the \*(ia metrics +.TP 10 +.B $PCP_PMDAS_DIR/\*(ia/Install +installation script for the +.B pmda\*(ia +agent +.TP 10 +.B $PCP_PMDAS_DIR/\*(ia/Remove +undo installation script for the +.B pmda\*(ia +agent +.TP 10 +.B $PCP_LOG_DIR/pmcd/\*(ia.log +default log file for error messages and other information from +.B pmda\*(ia +.PD +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.B /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). +.SH SEE ALSO +.BR PCPIntro (1), +.BR pmcd (1), +.BR pmdasample (1), +.BR pmdasimple (1), +.BR pmdatxmon (1) +and +.BR PMDA (3). diff --git a/man/man1/pmdatxmon.1 b/man/man1/pmdatxmon.1 new file mode 100644 index 0000000..2b9fdc2 --- /dev/null +++ b/man/man1/pmdatxmon.1 @@ -0,0 +1,192 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2012 Red Hat. +.\" Copyright (c) 2000 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.\" I am variants ... +.ds ia txmon +.ds IA TXMON +.ds Ia Txmon +.TH PMDATXMON 1 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmdatxmon\f1 \- \*(ia performance metrics domain agent (PMDA) +.SH SYNOPSIS +\f3$PCP_PMDAS_DIR/\*(ia/pmda\*(ia\f1 +[\f3\-d\f1 \f2domain\f1] +[\f3\-l\f1 \f2logfile\f1] +[\f3\-U\f1 \f2username\f1] +\f2tx_type\f1 ... +.br +\f3$PCP_PMDAS_DIR/\*(ia/txrecord\f1 +[\f3\-l\f1] +.br +\f3$PCP_PMDAS_DIR/\*(ia/txrecord\f1 +\f2tx_type servtime\f1 [\f2tx_type servtime\f1 ... ] +.br +\f3$PCP_PMDAS_DIR/\*(ia/genload\f1 +.SH DESCRIPTION +.B pmda\*(ia +is an example Performance Metrics Domain Agent (PMDA) which exports +a small number of performance metrics from a simulated transaction +monitor. +.PP +The \*(ia PMDA is +shipped as both binary and source code and is designed to be +an aid for PMDA developers; +the \*(ia PMDA demonstrates how performance +data can be exported from an application (in this case +.BR txrecord ) +to the PCP infrastructure via a shared memory segment. +As a matter of convenience, +.B pmda\*(ia +creates (and destroys on exit) the shared memory segment. +.PP +The +.I tx_type +arguments are arbitrary unique tags used to identify different +transaction types. +.PP +The +.B txrecord +application simulates the processing of one or more transactions identified +by +.I tx_type +and with an observed service time of +.I servtime . +.PP +With the +.B \-l +option, +.B txrecord +displays the current summary of the transaction activity from +the shared memory segment. +.PP +.B genload +is a shell and +.BR awk (1) +script that acts as a front-end to +.B txrecord +to generate a constant load of simulated transaction activity. +.PP +A brief description of the +.B pmda\*(ia +command line options follows: +.TP 5 +.B \-d +It is absolutely crucial that the performance metrics +.I domain +number specified here is unique and consistent. +That is, +.I domain +should be different for every PMDA on the one host, and the same +.I domain +number should be used for the same PMDA on all hosts. +.TP +.B \-l +Location of the log file. By default, a log file named +.I \*(ia.log +is written in the current directory of +.BR pmcd (1) +when +.B pmda\*(ia +is started, i.e. +.BR $PCP_LOG_DIR/pmcd . +If the log file cannot +be created or is not writable, output is written to the standard error instead. +.TP 5 +.B \-U +User account under which to run the agent. +The default is the unprivileged "pcp" account in current versions of PCP, +but in older versions the superuser account ("root") was used by default. +.SH INSTALLATION +If you want access to the names, help text and values for the \*(ia +performance metrics, do the following as root: +.PP +.ft CW +.nf +.in +0.5i +# cd $PCP_PMDAS_DIR/\*(ia +# ./Install +.in +.fi +.ft 1 +.PP +You will be prompted for the +.I tx_type +tags. +.PP +If you want to undo the installation, do the following as root: +.PP +.ft CW +.nf +.in +0.5i +# cd $PCP_PMDAS_DIR/\*(ia +# ./Remove +.in +.fi +.ft 1 +.PP +.B pmda\*(ia +is launched by +.BR pmcd (1) +and should never be executed directly. +The Install and Remove scripts notify +.BR pmcd (1) +when the agent is installed or removed. +.SH FILES +.PD 0 +.TP 10 +.B $PCP_PMCDCONF_PATH +command line options used to launch +.B pmda\*(ia +.TP +.B $PCP_PMDAS_DIR/\*(ia/help +default help text file for the \*(ia metrics +.TP +.B $PCP_PMDAS_DIR/\*(ia/Install +installation script for the +.B pmda\*(ia +agent +.TP +.B $PCP_PMDAS_DIR/\*(ia/Remove +undo installation script for the +.B pmda\*(ia +agent +.TP +.B $PCP_LOG_DIR/pmcd/\*(ia.log +default log file for error messages and other information from +.B pmda\*(ia +.PD +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.B /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). +.SH SEE ALSO +.BR PCPIntro (1), +.BR pmcd (1), +.BR pmdasample (1), +.BR pmdatrivial (1), +.BR txmonvis (1) +and +.BR PMDA (3). diff --git a/man/man1/pmdaweblog.1 b/man/man1/pmdaweblog.1 new file mode 100644 index 0000000..2558d2e --- /dev/null +++ b/man/man1/pmdaweblog.1 @@ -0,0 +1,584 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2012 Red Hat. +.\" Copyright (c) 2000 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMDAWEBLOG 1 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmdaweblog\f1 \- performance metrics domain agent (PMDA) for Web server logs +.\" literals use .B or \f3 +.\" arguments use .I or \f2 +.SH SYNOPSIS +\f3$PCP_PMDAS_DIR/weblog/pmdaweblog\f1 +[\f3\-Cp\f1] +[\f3\-d\f1 \f2domain\f1] +[\f3\-h\f1 \f2helpfile\f1] +[\f3\-i\f1 \f2port\f1] +[\f3\-l\f1 \f2logfile\f1] +[\f3\-n\f1 \f2idlesec\f1] +[\f3\-S\f1 \f2num\f1] +[\f3\-t\f1 \f2delay\f1] +[\f3\-u\f1 \f2socket\f1] +[\f3\-U\f1 \f2username\f1] +\f2configfile\f1 +.SH DESCRIPTION +.B pmdaweblog +is a Performance Metrics Domain Agent +.RB ( PMDA (3)) +that scans Web server logs +to extract metrics characterizing Web server activity. +These performance metrics are then made available through the infrastructure +of the Performance Co-Pilot (PCP). +.PP +The +.I configfile +specifies which Web servers are to be monitored, their associated access +logs and error logs, and a regular-expression based scheme for extracting +detailed information about each Web access. This file is maintained as +part of the PMDA installation and/or de-installation by the scripts +.B Install +and +.B Remove +in the directory +.BR $PCP_PMDAS_DIR/weblog . +For more details, refer to the section below covering installation. +.PP +Once started, +.B pmdaweblog +monitors a set of log files and in response to a request for information, +will process any new information that has been appended to the log files, +similar to a +.BR tail (1). +There is also periodic "catch up" to process new information from all +log files, and a scheme to detect the rotation of log files. +.PP +Like all other PMDAs, +.B pmdaweblog +is launched by +.BR pmcd (1) +using command line options specified in +.I $PCP_PMCDCONF_PATH +\- the +.B Install +script will prompt for appropriate values for the command line options, and +update +.IR $PCP_PMCDCONF_PATH . +.PP +A brief description of the +.B pmdaweblog +command line options follows: +.TP +.B \-C +Check the configuration and exit. +.TP +.BI \-d " domain" +Specify the +.I domain +number. It is absolutely crucial that the performance metrics +.I domain +number specified here is unique and consistent. That is, +.I domain +should be different for every PMDA on the one host, and the same +.I domain +number should be used for the +.B pmdaweblog +PMDA on all hosts. +.RS +.P +For most installations, the default +.I domain +as encapsulated in the file +.B $PCP_PMDAS_DIR/weblog/domain.h +will suffice. For alternate values, check +.I $PCP_PMCDCONF_PATH +for the +.I domain +values already in use on this host, and the file +.B $PCP_VAR_DIR/pmns/stdpmid +contains a repository of ``well known'' +.I domain +assignments that probably should be avoided. +.RE +.TP +.BI \-h " helpfile" +Get the help text from the supplied +.I helpfile +rather than from the default location. +.TP +.BI \-i " port" +Communicate with +.BR pmcd (1) +on the specified Internet +.I port +(which may be a number or a name). +.TP +.BI \-l " logfile" +Location of the log file. By default, a log file named +.I weblog.log +is written in the current directory of +.BR pmcd (1) +when +.B pmdaweblog +is started, i.e. +.BR $PCP_LOG_DIR/pmcd . +If the log file cannot +be created or is not writable, output is written to the standard error instead. +.TP +.BI \-n " idlesec" +If a Web server log file has not been modified for +.IR idlesec +seconds, then the file will be closed and re-opened. +This is the only way +.B pmdaweblog +can detect any asynchronous rotation of the logs by Web server +administrative scripts. +The default period is 20 seconds. +This value may be changed dynamically using +.BR pmstore (1) +to modify the value of the performance metric +.BR web.config.check . +.I +.TP +.B \-p +Communicate with +.BR pmcd (1) +via a pipe. +.TP +.BI \-S " num" +Specify the maximum number of Web servers per +.IR sproc . +It may be desirable (from a latency and load balancing perspective) or +necessary (due to file descriptor limits) to delegate responsibility +for scanning the Web server log files to several +.IR sprocs . +.B pmdaweblog +will ensure that each +.I sproc +handles the log files for at most +.I num +Web servers. +The default value is 80 Web servers per +.IR sproc . +.TP +.BI \-t " delay" +To avoid the need to scan a lot of information from the Web +server logs in response to a single request for performance +metrics, all log files will be checked at least once +every +.I delay +seconds. +The default is 15 seconds. +This value may by changed dynamically using +.BR pmstore (1) +to modify the value of the performance metric +.BR web.config.catchup . +.TP +.BI \-u " socket" +Communicate with +.BR pmcd (1) +via the given Unix domain +.IR socket . +.TP +.B \-U +User account under which to run the agent. +The default is the unprivileged "pcp" account in current versions of PCP, +but in older versions the superuser account ("root") was used by default. +.SH INSTALLATION +The PCP framework allows metrics to be collected on one host +and monitored from another. These hosts are referred to as +.I collector +and +.I monitor +hosts, respectively. A host may be both a collector and a monitor. +.PP +Collector hosts require the installation of the agent, while monitoring +hosts require no agent installation at all. +.PP +For collector hosts do the following as root: +.PP +.ft CW +.nf +.in +0.25i +# cd $PCP_PMDAS_DIR/weblog +# ./Install +.in +.fi +.ft 1 +.PP +The installation procedure prompts for a default or non-default installation. +A default installation will search for known server configurations and +automatically configure the PMDA for any server log files that are found. +A non-default installation will step through each server, prompting the +user for other server configurations and arguments to +.BR pmdaweblog . +The end result of a collector installation +is to build a configuration file that is passed to +.B pmdaweblog +via the +.I configfile +argument. +.PP +If you want to undo the installation, do the following as root: +.PP +.ft CW +.nf +.in +0.25i +# cd $PCP_PMDAS_DIR/weblog +# ./Remove +.in +.fi +.ft 1 +.PP +.B pmdaweblog +is launched by +.BR pmcd (1) +and should never be executed directly. +The +.B Install +and +.B Remove +scripts notify +.BR pmcd (1) +when the agent is installed or removed. +.SH CONFIGURATION +The configuration file for the weblog PMDA is an ASCII file that can +be easily modified. +Empty lines and lines beginning with '\f3#\f1' +are ignored. +All other lines must be either a regular expression or server +specification. +.PP +Regular expressions, which are used on both the access and error log files, +must be of the form: +.PP +.in +0.25i +.B regex +.I regexName regexp +.in +.I or +.PP +.in +0.25i +.B regex_posix +.I regexName ordering regexp_posix +.in +.PP +The +.I regexName +is a word which uniquely identifies the regular expression. +This is the reference used in the server specification. +The +.I regexp +for access logs is in the format described for +.BR regcmp (3). +The +.I regexp_posix +for access logs is in the format described for +.BR regcomp (3). +The argument +.I ordering +is explained below. The +.B Posix +form should be available on all platforms. +.PP +The regular expression requires the specification of up to four arguments +to be extracted from each line of a Web server access log, depending on the +type of server. In the most common case there are two arguments representing +the method and the size. +.PP +For the non\- +.B Posix +version, argument +.I $0 +should contain the method: +.BR GET , +.B HEAD , +.B POST +or +.BR PUT . +The method +.B PUT +is treated as a synonym for +.BR POST , +and anything else is categorized as +.BR OTHER . +.PP +The second argument, +.IR $1 , +should contain the size of the request. +A size of ``\f3\-\f1'' or `` '' is treated as unknown. +.PP +Argument +.I $3 +should contain the status code returned to the client browser and argument +.I $4 +should contain the status code returned to the server from a remote host. +These latter two arguments are used for caching servers and must be specified +as a pair (or +.I $3 +will be ignored). For further information on status codes, refer to the +web site +.B http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html +.PP +Some legal non\- +.B Posix +regex expression specifications for monitoring an access log are: +.PP +.ft CW +.nf +.in +0.25i +# pattern for CERN, NCSA, Netscape etc Access Logs +regex CERN ] "([A\-Za\-z][\-A\-Za\-z]+)$0 .*" [\-0\-9]+ ([\-0\-9]+)$1 + +# pattern for FTP Server access logs (normally in SYSLOG) +regex SYSLOG_FTP ftpd[.*]: ([gp][\-A\-Za\-z]+)$0( )$1 +.in +.fi +.ft 1 +.PP +There is 1 special types of access logs with the +.I RegexName +.I SQUID. +This formats extract 4 parameters but since the +.B Squid +log file uses text-based status codes, it is handled as a special case. +.PP +In the examples below, +.I NS_PROXY +parses the Netscape/W3C +.I Common Extended Log Format +and +.I SQUID +parses the default Squid Object Cache format log file. +.PP +.ft CW +.nf +.in +0.25i +# pattern for Netscape Proxy Server Extended Logs +regex NS_PROXY ] "([A\-Za\-z][\-A\-Za\-z]+)$0 .*" ([\-0\-9]+)$2 \\ +.in +0.5i +([\-0\-9]+)$1 ([\-0\-9]+)$3 +.in + +# pattern for Squid Cache logs +regex SQUID [0\-9]+\.[0\-9]+[ ]+[0\-9]+ [a\-zA\-Z0\-9\.]+ \\ +.in +0.5i +([_A\-Z]+)$3\/([0\-9]+)$2 ([0\-9]+)$1 ([A\-Z]+)$0 +.in +.in +.fi +.ft 1 +.PP +The +.I regexp +for the error logs does not require any arguments, only a match. +Some legal +expressions are: +.PP +.ft CW +.nf +.in +0.25i +# pattern for CERN, NCSA, Netscape etc Error Logs +regex CERN_err . + +# pattern for FTP Server error logs (normally in SYSLOG) +regex SYSLOG_FTP_err FTP LOGIN FAILED +.in +.fi +.ft 1 +.PP +If +.B POSIX +compliant regular expressions are used, additional information is required +since the order of parameters cannot be specified in the regular expression. +For backwards compatibility, the common case of two parameters the order +may be specified as +.I method,size +or +.I size,method +In the general case, the ordering is specified by one of the following +methods: +.TP 0.5in +n1,n2,n3,n4 +where nX is a digit between 1 and 4. Each comma-seperated field represents +(in order) the argument number for +.I method,size,client_status,server_status +.TP 0.5in +- +Used for cases like the error logs where the content is ignored. +.PP +As for the non- +.B Posix +format, the +.I SQUID +RegexName is treated as a special case to match the non-numerical status codes. +.PP +Some legal +.B Posix +regex expression specifications for monitoring an access log are: +.PP +.ft CW +.nf +.in +0.25i +# pattern for CERN, NCSA, Netscape, Apache etc Access Logs +regex_posix CERN method,size ][ \\]+"([A\-Za\-z][\-A\-Za\-z]+) \\ +.in +0.5i +[^"]*" [\-0\-9]+ ([\-0\-9]+) +.in + +# pattern for CERN, NCSA, Netscape, Apache etc Access Logs +regex_posix CERN 1,2 ][ \\]+"([A\-Za\-z][\-A\-Za\-z]+) \\ +.in +0.5i +[^"]*" [\-0\-9]+ ([\-0\-9]+) +.in + +# pattern for FTP Server access logs (normally in SYSLOG) +regex_posix SYSLOG_FTP method,size ftpd[.*]: \\ +.in +0.5i +([gp][\-A\-Za\-z]+)( ) +.in + +# pattern for Netscape Proxy Server Extended Logs +regex_posix NS_PROXY 1,3,2,4 ][ ]+"([A\-Za\-z][\-A\-Za\-z]+) \\ +.in +0.5i +[^"]*" ([\-0\-9]+) ([\-0\-9]+) ([\-0\-9]+) +.in + +# pattern for Squid Cache logs +regex_posix SQUID 4,3,2,1 [0\-9]+\.[0\-9]+[ ]+[0\-9]+ \\ +.in +0.5i +[a\-zA\-Z0\-9\.]+ ([_A\-Z]+)\/([0\-9]+) ([0\-9]+) ([A\-Z]+) +.in + +# pattern for CERN, NCSA, Netscape etc Error Logs +regex_posix CERN_err \- . + +# pattern for FTP Server error logs (normally in SYSLOG) +regex_posix SYSLOG_FTP_err \- FTP LOGIN FAILED +.in +.fi +.ft 1 + +.PP +A Web server can be specified using this syntax: +.PP +.ft CW +.nf +.in +0.25i +\f3server \f2serverName \f3on\f2|\f3off \f2accessRegex accessFile errorRegex errorFile +.in +.fi +.ft 1 +.PP +The +.I serverName +must be unique for each server, and is the name given to the instance +for the associated performance metrics. +See +.BR PMAPI (3) +for a discussion of PCP instance domains. +The +.B on +or +.B off +flag indicates whether the server is to be monitored when the PMDA is +installed. +This can altered dynamically using +.BR pmstore (1) +for the metric +.BR web.perserver.watched , +which has one instance for each Web server named in +.IR configfile . +.PP +Two files are monitored for each Web server, the access and the error log. +Each file requires the name of a previously declared regular expression, +and a file name. +The log files specified for each server do not +have to exist when the weblog PMDA is installed. +The PMDA will continue +to check for non-existent log files and open them when possible. +Some legal server specifications are: +.PP +.ft CW +.nf +.in +0.25i +# Netscape Server on Port 80 at IP address 127.55.555.555 +server 127.55.555.555:80 on CERN /logs/access CERN_err /logs/errors + +# FTP Server. +server ftpd on SYSLOG_FTP /var/log/messages SYSLOG_FTP_err /var/log/messages +.in +.fi +.ft 1 +.SH CAVEATS +Specifying regular expressions with an incorrect number of arguments, anything other +than 2 for access logs, and none for error logs, may cause the PMDA to behave +incorrectly and even crash. This is due to limitations in the interface of +.BR regex (3). +.SH FILES +.TP 10 +.B $PCP_PMDAS_DIR/weblog +installation directory for the weblog PMDA +.TP +.B $PCP_PMDAS_DIR/weblog/Install +installation script for the weblog PMDA +.TP +.B $PCP_PMDAS_DIR/weblog/Remove +de-installation script for the weblog PMDA +.TP +.B $PCP_LOG_DIR/pmcd/weblog.log +default log file for error reporting +.TP +.I $PCP_PMCDCONF_PATH +.B pmcd +configuration file that specifies the command line options +to be used when +.B pmdaweblog +is launched +.TP +.B $PCP_LOG_DIR/NOTICES +log of PMDA installations and removals +.TP +.B $PCP_VAR_DIR/config/web/weblog.conf +likely location of the weblog PMDA configuration file +.TP +.B $PCP_DOC_DIR/pcpweb/index.html +the online HTML documentation for PCPWEB +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.B /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). +.SH SEE ALSO +.BR pmcd (1), +.BR pmchart (1), +.BR pmdawebping (1), +.BR pminfo (1), +.BR pmstore (1), +.BR pmview (1), +.BR tail (1), +.BR weblogvis (1), +.BR webvis (1), +.BR PMAPI (3), +.BR PMDA (3) +and +.BR regcmp (3). diff --git a/man/man1/pmdaxfs.1 b/man/man1/pmdaxfs.1 new file mode 100644 index 0000000..23a3276 --- /dev/null +++ b/man/man1/pmdaxfs.1 @@ -0,0 +1,143 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2014 Red Hat. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.TH PMDAXFS 1 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmdaxfs\f1 \- XFS filesystem performance metrics domain agent (PMDA) +.SH SYNOPSIS +\f3$PCP_PMDAS_DIR/xfs/pmdaxfs\f1 +[\f3\-d\f1 \f2domain\f1] +[\f3\-l\f1 \f2logfile\f1] +.SH DESCRIPTION +.B pmdaxfs +is a Performance Metrics Domain Agent (PMDA) which extracts +performance metrics describing the state of the XFS filesystem +from the Linux kernel. +.PP +The +.B xfs +PMDA exports metrics that measure information about metadata buffer +usage, the journal, btree operations, inode operations, extended +attributes, directories, quotas, read and write operation counts +and of course throughput. +.PP +The PMDA provides a facility to reset the values of all counters +to zero using +.BR pmstore (1) +with the xfs.control.reset metric. +.PP +A brief description of the +.B pmdaxfs +command line options follows: +.TP 5 +.B \-d +It is absolutely crucial that the performance metrics +.I domain +number specified here is unique and consistent. +That is, +.I domain +should be different for every PMDA on the one host, and the same +.I domain +number should be used for the same PMDA on all hosts. +.TP +.B \-l +Location of the log file. By default, a log file named +.I xfs.log +is written in the current directory of +.BR pmcd (1) +when +.B pmdaxfs +is started, i.e. +.BR $PCP_LOG_DIR/pmcd . +If the log file cannot +be created or is not writable, output is written to the standard error instead. +.SH INSTALLATION +The +.B xfs +PMDA is installed and available by default on Linux. +If you want to undo the installation, do the following as root: +.PP +.ft CW +.nf +.in +0.5i +# cd $PCP_PMDAS_DIR/xfs +# ./Remove +.in +.fi +.ft 1 +.PP +If you want to establish access to the names, help text and values for the XFS +performance metrics once more, after removal, do the following as root: +.PP +.ft CW +.nf +.in +0.5i +# cd $PCP_PMDAS_DIR/xfs +# ./Install +.in +.fi +.ft 1 +.PP +.B pmdaxfs +is launched by +.BR pmcd (1) +and should never be executed directly. +The Install and Remove scripts notify +.BR pmcd (1) +when the agent is installed or removed. +.SH FILES +.PD 0 +.TP 10 +.B $PCP_PMCDCONF_PATH +command line options used to launch +.B pmdaxfs +.TP 10 +.B $PCP_PMDAS_DIR/xfs/help +default help text file for the xfs metrics +.TP 10 +.B $PCP_PMDAS_DIR/xfs/Install +installation script for the +.B pmdaxfs +agent +.TP 10 +.B $PCP_PMDAS_DIR/xfs/Remove +undo installation script for the +.B pmdaxfs +agent +.TP 10 +.B $PCP_LOG_DIR/pmcd/xfs.log +default log file for error messages and other information from +.B pmdaxfs +.PD +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.I /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). +.SH SEE ALSO +.BR PCPIntro (1), +.BR pmcd (1), +.BR pmstore (1), +.BR pcp.conf (5) +and +.BR pcp.env (5). diff --git a/man/man1/pmdazswap.1 b/man/man1/pmdazswap.1 new file mode 100644 index 0000000..6a736dd --- /dev/null +++ b/man/man1/pmdazswap.1 @@ -0,0 +1,66 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2014 Red Hat. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMDAZSWAP 1 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmdazswap\f1 \- zswap (compressed swap) PMDA +.SH DESCRIPTION +\f3pmdazswap\f1 is a Performance Metrics Domain Agent (PMDA) which exports +metric values about compressed swap operation, as tracked by the +.B zswap +Linux kernel module. +.PP +Zswap is a lightweight compressed cache for swap pages. +It takes pages that are in the process of being swapped out and attempts +to compress them into a dynamically allocated RAM-based memory pool. +Zswap trades CPU cycles for potentially reduced swap I/O. +This tradeoff can also result in a performance improvement if reads +from the compressed cache are faster than reads from a swap device. +.PP +This PMDA exports metrics about pool size, number of pages stored, and +various counters for the reasons pages are rejected. +.SH INSTALLATION +Install the zswap PMDA by using the Install script as root: +.PP + # cd $PCP_PMDAS_DIR/zswap +.br + # ./Install +.PP +To uninstall, do the following as root: +.PP + # cd $PCP_PMDAS_DIR/zswap +.br + # ./Remove +.PP +\fBpmdazswap\fR is launched by \fIpmcd\fR(1) and should never be executed +directly. The Install and Remove scripts notify \fIpmcd\fR(1) when the +agent is installed or removed. +.SH FILES +.IP "\fB$PCP_PMDAS_DIR/zswap/Install\fR" 4 +installation script for the \fBpmdazswap\fR agent +.IP "\fB$PCP_PMDAS_DIR/zswap/Remove\fR" 4 +undo installation script for the \fBpmdazswap\fR agent +.IP "\fB$PCP_LOG_DIR/pmcd/zswap.log\fR" 4 +default log file for error messages from \fBpmdazswap\fR +.SH PCP ENVIRONMENT +Environment variables with the prefix \fBPCP_\fR are used to parameterize +the file and directory names used by \fBPCP\fR. On each installation, the +file \fB/etc/pcp.conf\fR contains the local values for these variables. +The \fB$PCP_CONF\fR variable may be used to specify an alternative +configuration file, as described in \fIpcp.conf\fR(5). +.SH SEE ALSO +.BR pmcd (1) +and +.BR PCPIntro (1). diff --git a/man/man1/pmdbg.1 b/man/man1/pmdbg.1 new file mode 100644 index 0000000..8bc12fb --- /dev/null +++ b/man/man1/pmdbg.1 @@ -0,0 +1,73 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMDBG 1 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmdbg\f1 \- translate Performance Co-Pilot debug control flags +.\" literals use .B or \f3 +.\" arguments use .I or \f2 +.SH SYNOPSIS +\f3pmdbg\f1 +\f2code\f1 ... +.br +\f3pmdbg\f1 +\f3\-l\f1 +.SH DESCRIPTION +The components of the Performance Co-Pilot (PCP) use +a global vector of bit-fields +to control diagnostic and debug output. +.PP +.B pmdbg +with a +.B \-l +argument prints out the mnemonic and decimal values of all +the bit-fields in the debug control vector. +.PP +In the alternative usage, the +.I code +arguments are values for the debug vector, and the bit-fields that +are enabled by each of these values is listed. +.PP +Each +.I code +may be an integer, a hexadecimal value or a hexadecimal value prefixed +by either ``0x'' or ``0X''. +.PP +Most applications using the facilities of the PCP support +a +.BI \-D N +command-line syntax to enable debug control. +.B pmdbg +is designed to help choose an appropriate value for +.IR N . +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.I /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). +.SH SEE ALSO +.BR PCPIntro (1), +.BR pcp.conf (5) +and +.BR pcp.env (5). diff --git a/man/man1/pmdiff.1 b/man/man1/pmdiff.1 new file mode 100644 index 0000000..143cf36 --- /dev/null +++ b/man/man1/pmdiff.1 @@ -0,0 +1,167 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2013-2014 Red Hat. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMWTF 1 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmdiff\f1 \- compares archives and report significant differences +.SH SYNOPSIS +\f3pmdiff\f1 +[\f3\-d\f1/\f3--keep\f1] +[\f3\-z\f1/\f3--hostzone\f1] +[\f3\-p\f1/\f3--precision\f1 \f2precision\f1] +[\f3\-q\f1/\f3--threshold\f1 \f2thres\f1] +[\f3\-S\f1/\f3--start\f1 \f2starttime\f1] +[\f3\-T\f1/\f3--finish\f1 \f2endtime\f1] +[\f3\-B\f1/\f3--begin\f1 \f2starttime\f1] +[\f3\-E\f1/\f3--end\f1 \f2endtime\f1] +[\f3\-x\f1 \f2metric\f1] +[\f3\-X\f1 \f2file\f1] +[\f3--skip-excluded\f1] +[\f3--skip-missing\f1] +[\f3\-Z\f1/\f3--timezone\f1 \f2timezone\f1] +\f2archive1\f1 +[\f2archive2\f1] +.SH DESCRIPTION +.B pmdiff +compares the average values for every metric in either one +or two archives, in a given time window, for changes that are +likely to be of interest when searching for performance regressions. +.PP +The archive log has the base name +.I archive +and must have been previously created using +.BR pmlogger (1). +The +.BR pmlogsummary (1) +utility is used to obtain the average values used for comparison. +.PP +There are two sorts of invocation of the tool: with either one or +two archives. +.PP +In the first case, the only sensible command line requires use of +all four time window arguments. These are specified using the same +time window format described in +.BR PCPIntro (1), +and are +.BR \-S / \-\-start +and +.BR \-T / \-\-finish +for the start and end times of the first time window of interest +in the archive, and +.BR \-B / \-\-before +and +.BR \-E / \-\-end +for the start and end times of the second time window of interest. +.PP +In the second case, with two archives, the +.BR \-B / \-\-before +and +.BR \-E / \-\-end +options might be unnecessary. This might be the case, for example, +when comparing the same time window of two consecutive days (usually +two separate archives), or a time window on the same day of different +weeks. +.PP +In either case, +.B pmdiff +produces a sorted summary of those metrics in the specified window +whose values have deviated the most from a minimal threshold. +The level of deviation is calculated by dividing the average value +of each metric in both logs, and then calculating whether the ratio +falls outside of a range considered normal. +This ratio can be adjusted using the +.BR \-q / \-\-threshold +option, and by default it is 2 (i.e. report all metrics with average +values that have more than doubled in the two time windows or more +than halved in the two time windows). +.PP +Should any metrics be present in one window but missing from the +other, a diagnostic will be displayed listing each missing metric +and the archive from which it was missing. +.PP +The remaining options control the specific information to be reported. +Metrics with counter semantics are converted to rates before being +evaluated. +.TP 5 +.BR \-p / \-\-precision +Print all floating point numbers with +.I precision +digits after the decimal place. +.TP +.B \-\-skip-excluded +Cull the list of names of metrics being excluded from the output. +.TP +.B \-\-skip-missing +By default, +.B pmdiff +will report the names of any metrics that are in one archive but not +the other. +This option suppresses that reporting. +.TP +.B \-x +Compare each metric in each archive in the time windows specified +to a given +.BR egrep (1) +pattern, excluding those that match from the report output. +.TP +.B \-X +Allows a +.IR file +to be specified which containing +.BR egrep (1) +patterns which are applied to the metric names to optionally exclude +some from the report. +.TP +.B \-z +Use the local timezone from the given archives. +.TP +.BR \-Z / \-\-timezone +Changes the timezone in the archive labels to +.I timezone +in the format of the environment variable +.B TZ +as described in +.BR environ (5). +.PP +.SH FILES +.PD 0 +.TP 10 +.BI $PCP_LOG_DIR/pmlogger/ hostname +Default directory for PCP archives containing performance +metric values collected from the host +.IR hostname . +.PD +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.I /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). +.SH SEE ALSO +.BR PCPIntro (1), +.BR pmlogger (1), +.BR pmlogsummary (1), +.BR egrep (1), +.BR pcp.conf (5) +and +.BR pcp.env (5). diff --git a/man/man1/pmdumplog.1 b/man/man1/pmdumplog.1 new file mode 100644 index 0000000..deb3265 --- /dev/null +++ b/man/man1/pmdumplog.1 @@ -0,0 +1,242 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMDUMPLOG 1 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmdumplog\f1 \- dump internal details of a performance metrics archive log +.SH SYNOPSIS +\f3pmdumplog\f1 +[\f3\-adiLlmrstxz\f1] +[\f3\-n\f1 \f2pmnsfile\f1] +[\f3\-S\f1 \f2starttime\f1] +[\f3\-T\f1 \f2endtime\f1] +[\f3\-Z\f1 \f2timezone\f1] +\f2archive\f1 +[\f2metricname\f1 ...] +.br +\f3pmdumplog\f1 +[\f3\-v\f1 \f2file\f1] +.SH DESCRIPTION +.B pmdumplog +dumps assorted control, metadata, index and state information from +the files of a Performance Co-Pilot (PCP) archive log. +The archive log has the base name +.I archive +and must have been previously created using +.BR pmlogger (1). +.PP +Normally +.B pmdumplog +operates on the distributed Performance Metrics Name Space (PMNS), however +if the +.B \-n +option is specified an alternative local PMNS is loaded +from the file +.IR pmnsfile. +.PP +If any +.I metricname +arguments appear, the report will be restricted to information relevant +to the named performance metrics. +If +.I metricname +is a non-leaf node in the namespace (see \c +.BR pmns (5)), +then +.B pmdumplog +will recursively descend the archive's namespace and report on all leaf nodes. +.PP +The options control the specific information to be reported. +.TP 5 +.B \-a +Report everything, i.e. the flags +.BR \-d , +.BR \-i , +.BR \-l , +.BR \-m , +.BR \-s +and +.BR \-t . +.TP +.B \-d +Display the metadata and descriptions for those performance metrics +that appear at least once in the archive: +see +.BR pmLookupDesc (3) +for more details on the metadata describing metrics. +.TP +.B \-i +Display the instance domains, and any variations in their instance +members over the duration of the archive: see +.BR pmGetInDom (3) +for more details on instance domains. +.TP +.B \-l +Dump the archive label, showing the log format version, +the time and date for the start and (current) end of the archive, and +the host from which the performance metrics values were collected. +.TP +.B \-L +Like +.BR \-l , +just a little more verbose. +.TP +.B \-m +Print the values for the performance metrics from the archive. +This is the default display option. +.RS +5n +.P +Metrics without an instance domain are reported as: +.br +.ti +2n +[\fItimestamp\fR] \fImetric-id\fR (\fImetric-name\fR): \fBvalue1\fR \fIvalue2\fR +.P +Metrics with an instance domain are reported as: +.br +.ti +2n +[\fItimestamp\fR] \fImetric-id\fR (\fImetric-name\fR): +.br +.ti +6n +\fBinst\fR [\fIinternal-id\fR \fBor\fR "\fIexternal-id\fR"] +\fBvalue1\fR \fIvalue2\fR +.P +The \fItimestamp\fR is only reported for the first metric in +a group of metrics sharing the same timestamp. +.RE +.TP +.B \-r +Process the archive in reverse order, from most recent to oldest +recorded metric values. +.TP +.B \-S +When using the +.B \-m +option, the report will be restricted to those records logged at or after +.IR starttime . +Refer to +.BR PCPIntro (1) +for a complete description of the syntax for +.IR starttime . +.TP +.B \-s +Report the size in bytes of each physical record in the archive. +.TP +.B \-T +When using the +.B \-m +option, the report will be restricted to those records logged before or at +.IR endtime . +Refer to +.BR PCPIntro (1) +for a complete description of the syntax for +.IR endtime . +.TP +.B \-t +Dump the temporal index that is used to provide accelerated access +to large archive files. +.RS +.PP +The integrity of the index will also be checked. If the index is +found to be corrupted, the ``*.index'' file can be renamed or removed +and the archive will still be accessible, however retrievals may take longer +without the index. Note however that a corrupted temporal index is +usually indicative of a deeper malaise that may infect all files in a +PCP archive. +.RE +.TP +.B \-v +Verbose mode. Dump the records from a physical archive file in +hexadecimal format. +In this +case +.I file +is the name of a single file, usually a basename (as would otherwise +appear as the +.I archive +command line argument), concatenated with ``.'' followed by one of +.B meta +(the metadata), +.B index +(the temporal index), or +a digit (one of the volumes of metric values). +.sp 1.5v +Use of +.B \-v +precludes the use of all other options and arguments. +.TP +.B \-x +Extended timestamp reporting format that includes the day of the week, day of the month, +month and year in addition to the (default) hours, minutes and seconds time. +This is useful for archives that span multiple days. +.PP +By default, +.B pmdumplog +reports the time of day according to the local timezone on the +system where +.B pmdumplog +is run. +The +.B \-Z +option changes the timezone to +.I timezone +in the format of the environment variable +.B TZ +as described in +.BR environ (5). +The +.B \-z +option changes the timezone to the local timezone at the +host that is the source of the performance metrics, as specified in +the label record of the archive log. +.SH FILES +.PD 0 +.TP 10 +.BI $PCP_VAR_DIR/pmns/ * +default local PMNS specification files +.TP +.BI $PCP_LOG_DIR/pmlogger/ hostname +Default directory for PCP archives containing performance +metric values collected from the host +.IR hostname . +.PD +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.I /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). +.SH SEE ALSO +.BR PCPIntro (1), +.BR pmlogcheck (1), +.BR pmlogger (1), +.BR pmlogger_check (1), +.BR pmlogger_daily (1), +.BR pmloglabel (1), +.BR pmlogextract (1), +.BR PMAPI (3), +.BR pmGetInDom (3), +.BR pmLookupDesc (3), +.BR pcp.conf (5), +.BR pcp.env (5) +and +.BR pmns (5). diff --git a/man/man1/pmdumptext.1 b/man/man1/pmdumptext.1 new file mode 100644 index 0000000..5fffaa3 --- /dev/null +++ b/man/man1/pmdumptext.1 @@ -0,0 +1,423 @@ +'\"macro stdmacro +.TH PMDUMPTEXT 1 "SGI" "Performance Co-Pilot" +.SH NAME +\f3pmdumptext\f1 \- dump performance metrics to an ASCII table +.\" literals use .B or \f3 +.\" arguments use .I or \f2 +.SH SYNOPSIS +\f3pmdumptext\f1 +[\f3\-CFgGHilmMNoruXz\f1] +[\f3\-A\f1 \f2align\f1] +[\f3\-a\f1 \f2archive\f1[\f3,\f2archive\f3,\f1...]] +[\f3\-c\f1 \f2config\f1] +[\f3\-d\f1 \f2delimiter\f1] +[\f3\-f\f1 \f2format\f1] +[\f3\-h\f1 \f2host\f1] +[\f3\-n\f1 \f2pmnsfile\f1] +[\f3\-O\f1 \f2offset\f1] +[\f3\-p\f1 \f2port\f1] +[\f3\-P\f1 \f2precision\f1] +[\f3\-R\f1 \f2lines\f1] +[\f3\-s\f1 \f2sample\f1] +[\f3\-S\f1 \f2starttime\f1] +[\f3\-t\f1 \f2interval\f1] +[\f3\-T\f1 \f2endtime\f1] +[\f3\-U\f1 \f2string\f1] +[\f3\-w\f1 \f2width\f1] +[\f3\-Z\f1 \f2timezone\f1] +[\f2metric \f1...] +.SH DESCRIPTION +.B pmdumptext +outputs the values of performance metrics collected live or from a +Performance Co-Pilot (PCP) archive. +By default, the metric values are displayed in tab separated columns, +prefixed by a timestamp. +.PP +Unless directed to another host by the +.B \-h +option, or to one or more archives by the +.B \-a +option, +.B pmdumptext +will contact +.BR pmcd (1) +on the local host to obtain the required information. +.PP +.B pmdumptext +may be run in interactive mode with the +.B \-i +option which displays the values in equal width columns. Without this option, +no attempt is made to line up any values allowing the output to be easily +parsed by other applications. +.PP +The format of the output can be further controlled by changing the +precision of the values with +.BR \-P , +the width of the columns with +.BR \-w , +and the format of the values with the +.BR \-G +and +.BR \-F +options for the shortest of scientific or fixed digits, and a fixed +width format, respectively. +.PP +The +.I metrics +to be dumped can be listed on the command line, in a +.I config +file, or piped to +.B pmdumptext +on +.IR stdin . +A metric consists of an optional source (host or archive), the metric name, +and an optional instance list immediately after the name. A colon is used to +separate a host name from the metric, and a forward slash (``/'') to +separate an archive name from the metric. Instances are enclosed in square +brackets and a comma is used between each instance if more than one is stated. +For example, some legal metrics are: +.PP +.in 1.5i +.ft CW +.nf +kernel.all.cpu.idle +myhost:kernel.all.cpu.idle[cpu0,cpu3] +/path/to/myarchive/kernel.all.cpu.idle[cpu1] +.fi +.ft R +.in +.PP +The format of a metric is further described in +.BR PCPIntro (1). +A normalization value may optionally follow a metric name in a +.I config +file or on +.IR stdin . +The metric value will be scaled by this value. For example, if the file +system ``/dev/root'' has a capacity of 1965437 bytes, then the percentage of +the file system that is used could be dumped with this +.IR config : +.PP +.in 1.5i +.ft CW +.nf +filesys.used[/dev/root] 19654.37 +.fi +.ft R +.in +.PP +A normalization value may not be used with +.I metrics +specified as command line arguments. +.PP +A metric name is not required to be a leaf node in the Performance Metrics Name +Space (PMNS), except when one or more instances are specified. +For example, to dump all file system metrics, only +.I filesys +is required to dump +.IR filesys.capacity , +.IR filesys.used , +.IR filesys.free +etc. +.SH COMMAND LINE OPTIONS +The command line options +.BR \-A , +.BR \-O , +.B \-S +and +.B \-T +control the alignment, offset, start and end time when visualizing metrics +from archives. These options are common to most Performance Co-Pilot tools +and are fully described in +.BR PCPIntro (1). +.PP +The other available options are: +.PP +.IP \f3\-a\f1 +Specify an +.I archive +from which metrics can be obtained for a particular host. +.I archive +is the basename of an archive, previously created by +.BR pmlogger (1). +Multiple archives (separated by commas or in different \f3\-a\f1 options) +from different hosts may be given, but only one per host is +permitted. Any metrics that are not associated with a specific host or archive +will use the first archive as their source. +.IP \f3\-C\f1 +Exit before dumping any values, but after parsing the metrics. Metrics, +instances, normals and units are listed if +.BR \-m , +.BR \-l , +.BR \-N +and/or +.BR \-u +are specified. +.IP \f3\-c\f1 +If no +.I metrics +are listed on the command line, a +.I config +file can be used to specify the +.IR metrics +to be dumped. +Unlike the command line +.IR metrics , +each metric may be followed by a normalization value. Empty lines and +lines that begin with ``#'' are ignored. +.IP \f3\-d\f1 +Specify the +.I delimiter +that separates each column of output. The +.I delimiter +may only be a single character. +.IP \f3\-f\f1 +Use the +.I format +string for formatting the timestamp with each set of values. The syntax of +this string is the same as that described in +.BR strftime (3). +An empty +.I format +string (eg. '') will remove the timestamps from the output. +.IP \f3\-F\f1 +Output the values in a fixed width format of 6 characters. Positive +numbers are represented as \f2dd\f1.\f2dd\f3u\f1 and negative numbers as +\f3[\f1-\f3]\f2d\f1.\f2dd\f3u\f1. The postfix multiplier may have the values +.BR K (10^3), +.BR M (10^6), +.BR G (10^9) +and +.BR T (10^12). +For example, 4567 would be displayed as 4.57K, even if the units of the metric +are bytes. +.IP \f3\-G\f1 +Output the values using the shortest of a scientific format or a decimal +notation. +.IP \f3\-g\f1 +Run in graphical user interface (GUI) mode, with +.B pmtime +being used for VCR-alike time control functionality. +.IP \f3\-h\f1 +Fetch performance metrics from +.BR pmcd (1) +on +.IR host , +rather than the default localhost. +.IP \f3\-H\f1 +Show all headers before dumping any metric values. This is equivalent to +.BR \-lmNu . +.IP \f3\-i\f1 +Output the data in fixed width columns using fixed width values (see +.BR \-F ) +so that it is human-readable. This option may not be used with +.B \-P +as fixed point values are not fixed width. This option will also affect the +output of +.BR \-m +and +.BR \-u +options as the metric, instance and unit names will be truncated. +.IP \f3\-l\f1 +Show the source of the metrics. In interactive mode, the host of the metrics +is shown. In non-interactive mode, this option shows the source of +the metrics with the metric name even if +.B \-m +is not specified. +.IP \f3\-m\f1 +Output the metric names before the metric values. The source and units of +the metrics may also be dumped with the \f3\-l\f1 and \f3\-u\f1 options +respectively. If in interactive mode, the metrics names may be truncated, +and the instance names, where relevant, are also truncated on the follow +line. +.IP \f3\-M\f1 +Output the column number and complete metric names before dumping any values. +If the +.B \-l +flag is also specified, the source of the metrics is also shown. +.IP \f3\-n\f1 +Load an alternative local PMNS from the file +.IR pmnsfile. +.IP \f3\-o\f1 +When a timestamp is being reported (ie. unless an empty format string is +given with the +.B \-f +option), the timestamp is prefixed with the offset in seconds from +the start of the archive or the beginning of the execution of +.BR pmdumptext . +.IP \f3\-N\f1 +Output the normalization factors before the metric values. +.IP \f3\-p\f1 +Connect to +.BR pmtime (1) +on the specified +.IR port . +.IP \f3\-P\f1 +Set the +.I precision +of the values. This option may not be used with +.B \-F +as the precision is constant. The default precision is 3. +.IP \f3\-r\f1 +Output the raw metric values, do not convert counters to rates. This option +also causes +.B pmdumptext +to ignore the normalization values for each metric. +.IP \f3\-R\f1 +Repeat the header every +.I lines +of output. This option is useful in interactive mode when using a +graphical window to avoid the header scrolling beyond the window's buffer, +and to realign the header if the window is resized. +.IP \f3\-s\f1 +.B pmdumptext +will terminate after this many samples. +.IP \f3\-t\f1 +The +.I interval +argument follows the syntax described in +.BR PCPIntro (1), +and in the simplest form may be an unsigned integer (the implied +units in this case are seconds). +The default interval is 1.0 seconds. +.IP \f3\-u\f1 +Output the units of the metrics before the first values, but after the metric +names if \f3\-m\f1 is also specified. +.IP \f3\-U\f1 +Change the output when values are unavailable to +.IR string . +The default string is ``?''. +.IP \f3\-w\f1 +Set the column width of the output. Strings will be truncated to this width, +and maybe postfixed by ``...'' if the +.I width +is greater than 5. +.IP \f3\-X\f1 +Output the column number and complete metric names, one-per-line, +both before dumping the first set of values and again each time the +header is repeated. +.IP \f3\-z\f1 +Use the local timezone of the host that is the source of the +performance metrics, as identified by either the +.B \-h +or the first +.B \-a +options. +The default is to use the timezone of the local host. +.IP \f3\-Z\f1 +Use +.I timezone +when displaying the date and time. +.I Timezone +is in the format of the environment variable +.B TZ +as described in +.BR environ (5). +.SH MULTIPLE SOURCES +.B pmdumptext +supports the dumping of metrics from multiple hosts or archives. The metrics +listed on the command line or in the +.I config +file may have no specific source or come from different sources. +.PP +However, restrictions apply when archives +are specified on the command line +.RB ( \-a ) +and/or in the configuration file. Firstly, there may be only one archive +for any one host. Secondly, the hosts of any metrics with host sources +must correspond to the host of an archive, either on the command line or +previously as the source of another metric. +.PP +The options +.B \-a +and +.B \-h +may not be used together. +.SH UNIT CONVERSION +All metrics that have the semantics of counters are automatically converted to +rates over the sample time interval. In interactive mode, +.B pmdumptext +will also change the units of some metrics so that they are easier to +comprehend: +.TP +o +All metrics with space units (bytes to terabytes) are scaled to bytes. Note +that 1024 bytes with be represented as 1.02K, not 1.00K. +.TP +o +Metrics that are counters with time units (nanoseconds to hours) represent time +utilization over the sample interval. The unit strings of such metrics is +changed to ``Time Utilization'' or abbreviated to ``util'' and the values +are normalized to the range zero to one. +.SH EXAMPLES +o To examine the load on two hosts foo and bar, simultaneously: +.PP +.in 0.5i +.ft CW +.nf +$ pmdumptext \-il 'foo:kernel.all.load[1]' 'bar:kernel.all.load[1]' + Source foo bar +Wed Jul 30 11:37:53 0.309 0.409 +Wed Jul 30 11:37:54 0.309 0.409 +Wed Jul 30 11:37:55 0.309 0.409 +.fi +.ft R +.in +.PP +o To output the memory utilization on a remote host called bong with a simpler timestamp: +.PP +.in 0.5i +.ft CW +.nf +$ pmdumptext \-imu \-h bong \-f '%H:%M:%S' mem.util + Metric kernel fs_ctl _dirty _clean free user + Units b b b b b b +09:32:28 8.98M 0.97M 0.00 3.90M 7.13M 46.13M +09:32:29 8.99M 0.98M 0.00 5.71M 5.39M 46.03M +09:32:30 8.99M 1.07M 0.00 5.81M 4.55M 46.69M +09:32:31 9.03M 1.16M 0.00 6.45M 3.48M 47.00M +09:32:32 9.09M 1.18M 20.48K 6.23M 3.29M 47.30M +.fi +.ft R +.in +.PP +o To dump all metrics collected in an archive at a 30 second interval to a file +for processing by another tool: +.PP +.in 0.5i +.ft CW +.nf +$ pminfo \-a archive | pmdumptext \-t 30s \-m \-a archive > outfile +.fi +.ft R +.in +.SH FILES +.TP 10 +.B "$PCP_VAR_DIR/pmns/*" +default PMNS specification files +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.I /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (4). +.SH SEE ALSO +.BR pmchart (1), +.BR pmtime (1), +.BR PCPIntro (1), +.BR pmcd (1), +.BR pmlogger (1), +.BR pmlogextract (1), +.BR pmval (1), +.BR PMAPI (3), +.BR strftime (3) +and +.BR environ (5). diff --git a/man/man1/pmerr.1 b/man/man1/pmerr.1 new file mode 100644 index 0000000..8814290 --- /dev/null +++ b/man/man1/pmerr.1 @@ -0,0 +1,69 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMERR 1 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmerr\f1 \- translate Performance Co-Pilot error codes into error messages +.\" literals use .B or \f3 +.\" arguments use .I or \f2 +.SH SYNOPSIS +.B pmerr +.I code +\&... +.br +.B pmerr +\f3\-l\f1 +.SH DESCRIPTION +.B pmerr +accepts +standard Performance Co-Pilot (PCP) +error codes via the +.I code +argument(s) and generates the corresponding error text. +.PP +Each +.I code +may be an integer, a hexadecimal value or a hexadecimal value prefixed +by either ``0x'' or ``0X''. +.PP +Error codes must be less than zero, so if +.I code +is a positive number, a warning message is produced, and the +negated value is used. +.PP +The alternative use of the +.B \-l +option causes all known error codes to be listed, along with their +symbolic names and error text. +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.I /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). +.SH SEE ALSO +.BR PMAPI (3), +.BR pmErrStr (3), +.BR pcp.conf (5) +and +.BR pcp.env (5). diff --git a/man/man1/pmevent.1 b/man/man1/pmevent.1 new file mode 100644 index 0000000..e8a8ad9 --- /dev/null +++ b/man/man1/pmevent.1 @@ -0,0 +1,309 @@ +'\"! tbl | mmdoc +'\"macro stdmacro +.\" +.\" Copyright (c) 2000 Silicon Graphics, Inc. All Rights Reserved. +.\" Copyright (c) 2011 Ken McDonell. All Rights Reserved. +.\" Copyright (c) 2011 Nathan Scott. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMEVENT 1 "" "Performance Co-Pilot" +.SH NAME +\f3pmevent\f1 \- report event record details +.SH SYNOPSIS +\f3pmevent\f1 +[\f3\-gLz\f1] +[\f3\-a\f1 \f2archive\f1] +[\f3\-h\f1 \f2host\f1] +[\f3\-K\f1 \f2spec\f1] +[\f3\-O\f1 \f2offset\f1] +[\f3\-p\f1 \f2port\f1] +[\f3\-S\f1 \f2starttime\f1] +[\f3\-s\f1 \f2samples\f1] +[\f3\-T\f1 \f2endtime\f1] +[\f3\-t\f1 \f2interval\f1] +[\f3\-x\f1 \f2pattern\f1] +[\f3\-Z\f1 \f2timezone\f1] +\f2metricname\f1 ... +.SH DESCRIPTION +.de EX +.in +0.5i +.ie t .ft CB +.el .ft B +.ie t .sp .5v +.el .sp +.ta \\w' 'u*8 +.nf +.. +.de EE +.fi +.ie t .sp .5v +.el .sp +.ft R +.in +.. +Performance Co-Pilot (PCP) supports event records within the framework +for fetching general performance information. +.B pmevent +prints current or archived values for the nominated event record metrics. +The event records of interest are contained in one or more of the metrics +identified by the +.I metricname +arguments. +.PP +Unless directed to another host by the +.B \-h +option, +or to an archive by the +.B \-a +option +or to a local context by the +.B \-L +option, +.B pmevent +will contact the Performance Metrics Collector Daemon (PMCD) +on the local host to obtain the required information. +The +.BR \-a , \-h +and +.B \-L +options are mutually exclusive. +.PP +The +.I metricname +arguments may be given in the metric specification syntax, as +described in +.BR PCPIntro (1), +where the source and metric name may all be included in the +.IR metricname , +e.g. thathost:someagent.event.records +or +myarchive/someagent.event.records['foo-instance','bar-instance']. +When this format is used, any of the +.B \-h +or +.B \-a +or +.B \-L +options may also be specified, provided the usage is consistent +in terms of the source of the metrics identified by the options +as compared to any explicit source of the metrics defined in the +.I metricname +arguments. +.PP +When using the metric specification syntax, the ``hostname'' +.B @ +is treated specially and +causes +.B pmevent +to use a local context to collect metrics from PMDAs on the local host +without PMCD (same as the +.B \-L +option). Only some metrics are available in this mode. +.PP +The +.BR \-S , +.BR \-T +and +.BR \-O +options may be used to define a time window to restrict the +samples retrieved, set an initial origin within the time window; +refer to +.BR PCPIntro (1) +for a complete description of these options. +.PP +When processing an archive, +.B pmevent +may relinquish its own timing control, and operate as a ``slave'' of a +.BR pmtime (1) +process that uses a GUI dialog to provide timing control. +In this case, either the +.B \-g +option should be used to start +.B pmevent +as the sole slave of a new +.BR pmtime (1) +instance, or +.B \-p +should be used to attach +.B pmevent +to an existing +.BR pmtime (1) +instance via the IPC channel identified by the +.I port +argument. +.PP +The other options that control the information reported by +.B pmevent +are as follows: +.TP 5 +.B \-a +Performance metric values are retrieved from the PCP +archive log file identified by the base name +.IR archive . +.TP +.B \-g +Start +.B pmevent +as the slave of a new +.BR pmtime (1) +process for replay of archived performance data using the +.BR pmtime (1) +graphical user interface. +.TP +.B \-h +Current performance metric values are retrieved from the nominated +.I host +machine. +.TP +.B \-K +When +fetching metrics from a local context, the +.B \-K +option may be used to control the DSO PMDAs that should be +made accessible. The +.I spec +argument conforms to the syntax described in +.BR __pmSpecLocalPMDA (3). +More than one +.B \-K +option may be used. +.TP +.B \-L +Causes +.B pmevent +to use a local context to collect metrics from PMDAs on the local host +without PMCD. Only some metrics are available in this mode. +.TP +.B \-p +Attach +.B pmevent +to an existing +.BR pmtime (1) +time control process instance via the IPC channel identified by the +\f2port\f1 argument. +This option is normally only used by other tools, e.g. +.BR pmchart (1), +when they launch +.B pmevent +with synchronized time control. +.TP +.B \-s +The argument +.I samples +defines the number of samples to be retrieved and reported. +If +.I samples +is 0 or +.B \-s +is not specified, +.B pmevent +will sample and report continuously (in real time mode) or until the end +of the PCP archive (in archive mode). +.RS +.PP +It is not possible to control the number of event records, as each +value of a +.I metricname +may deliver zero, one or more event records. The +.B \-s +option determines how many times +.I pmevent +will retrieve values for the specified +.I metricname +metrics. +.RE +.TP +.B \-t +The default sampling \f2interval\f1 may be set to something other than the +default 1 second. +The +.I interval +argument follows the syntax described in +.BR PCPIntro (1), +and in the simplest form may be an unsigned integer (the implied +units in this case are seconds). +.RS +.PP +For PCP archives, +.I pmevent +will retrieve +.B all +of the event records for the +.I metricname +metrics within the requested time window, so the value of the +sampling interval will have no effect in this case. +.RE +.TP +.B \-x +The given +.I filter +is sent to the performance metric domain agent for the requested +.I metricname +before any values are requested. +This serves two purposes. +Firstly, it provides a mechanism for server-side event filtering +that is customisable for individual event streams. +In addition, some performance metrics domain agents also use the +PMCD store mechanism to provide a basic security model (e.g. for +sensitive log files, only a client host with +.BR pmStore (3) +access would be able to access the event stream). +.RE +.TP +.B \-Z +By default, +.B pmevent +reports the time of day according to the local timezone on the +system where +.B pmevent +is run. +The +.B \-Z +option changes the timezone to +.I timezone +in the format of the environment variable +.B TZ +as described in +.BR environ (5). +.TP +.B \-z +Change the reporting timezone to the local timezone at the host that is +the source of the performance metrics, as identified via either the +.I metricname +or the +.B \-h +or +.B \-a +or +.B \-L +options. +.PP +The output from +.B pmevent +is directed to standard output. +.SH SEE ALSO +.BR PCPIntro (1), +.BR pmcd (1), +.BR pmchart (1), +.BR pmdumplog (1), +.BR pminfo (1), +.BR pmlogger (1), +.BR pmtime (1), +.BR pmval (1), +.BR PMAPI (3), +.BR __pmSpecLocalPMDA (3), +.BR pcp.conf (5) +and +.BR pcp.env (5). +.SH DIAGNOSTICS +All are generated on standard error and are intended to be self-explanatory. diff --git a/man/man1/pmfind.1 b/man/man1/pmfind.1 new file mode 100644 index 0000000..f283d7d --- /dev/null +++ b/man/man1/pmfind.1 @@ -0,0 +1,104 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2014 Red Hat. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.TH PMFIND 1 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmfind\f1 \- find PCP services on the network +.SH SYNOPSIS +\f3pmfind\f1 +[\f3\-q\f1] +[\f3\-m\f1 \f2mechanism\f1] +[\f3\-s\f1 \f2service\f1] +.SH DESCRIPTION +.B pmfind +searches for instances of the specified PCP service being advertised on the +network and prints a list of URLs corresponding to the services discovered. +.PP +By default +.B pmfind +will search for all supported PCP services, however a specific PCP +.I service +to discover can be specified using the +.B \-s +option. Supported services are +.BR pmcd (1), +.BR pmproxy (1) +and +.BR pmwebd (1) . +.PP +The +.B \-m +option sets the +.I mechanism +that +.B pmfind +uses when performing service discovery. +By default, or if the keyword "all" is specified, every available +mechanism will be used (iteratively). Supported mechanisms are: +.TP +.B avahi +Searches for services which are broadcasting using mDNS via +.BR avahi-daemon(8). +.TP +.B probe=<net-address>/<mask-bits> +Actively probes the given subnet for the requested PCP service(s). +<net-address> is an inet or ipv6 +network address and <mask-bits> is the number of bits used to define the +subnet. For example, 192.168.1.0/24 defines an 8 bit subnet consisting of the +addresses 192.168.1.0 through 192.168.1.255. +An optional suffix \fB",maxThreads=N"\fP may be added to limit the number of +threads used while probing. The default is no fixed limit, which is to say that +the process' rlimits for the number of threads and open file descriptors +will be respected. +.PP +The +.B \-q +option suppresses all output on the standard output stream. +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.I /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). +.SH DIAGNOSTICS +The value of the exit status from the command is zero when services were +successfully located, one if no services were found, and two if an error +occurred. +.PP +In the event of an error, a message will be generated on standard error +that is intended to be self-explanatory. +.SH SIGNALS +.B pmfind +will interrupt the service discovery process when one of the following +signals is received: SIGHUP, SIGPIPE, SIGINT, SIGTERM, SIGXFSZ, SIGXCPU. +.B pmfind +will report any results which were discovered up to point of the interruption. +.SH SEE ALSO +.BR PCPIntro (1), +.BR pmcd (1), +.BR pmproxy (1), +.BR pmwebd (1), +.BR PMAPI (3), +.BR pmDiscoverServices (3), +.BR pcp.conf (5) +and +.BR pcp.env (5). diff --git a/man/man1/pmgenmap.1 b/man/man1/pmgenmap.1 new file mode 100644 index 0000000..7f3d0bb --- /dev/null +++ b/man/man1/pmgenmap.1 @@ -0,0 +1,274 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMGENMAP 1 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmgenmap\f1 \- generate C code to simplify handling of performance metrics +.\" literals use .B or \f3 +.\" arguments use .I or \f2 +.SH SYNOPSIS +\f3pmgenmap\f1 +[\f2infile\f1] +.SH DESCRIPTION +.de CW +.ie t \f(CW\\$1\f1\\$2 +.el \fI\\$1\f1\\$2 +.. +Given one or more lists of metric names in +.I infile +or on standard input, +.B pmgenmap +generates C declarations +and +.BR cpp (1) +macros suitable for use across the +Performance Metrics Programming Interface (PMAPI) +on standard output. +.PP +The declarations produced by +.B pmgenmap +simplify the coding for client applications using the PMAPI. +.PP +The input should consist of one or more lists of metric names of the form +.PP +.ft CW +.nf +.in +0.5i +listname { + metricname1 symbolname1 + metricname2 symbolname2 + ... +} +.in +.fi +.ft 1 +.PP +which will generate C and +.BR cpp (1) +declarations of the form +.PP +.ft CW +.nf +.in +0.5i +char *listname[] = { +#define symbolname1 0 + "metricname1", +#define symbolname2 1 + "metricname2", + ... +}; +.in +.fi +.ft 1 +.PP +The array declarations produced are suitable as parameters to +.BR pmLookupName (3) +and the +.BR #define d +constants may be used to index the +.CW vset s +in the +.CW pmResult +structure returned by a +.BR pmFetch (3) +call. +.PP +Obviously, +.CW listname +must conform to the C identifier naming rules, each +.CW symbolname +must conform to the +.BR cpp (1) +macro naming rules, and each +.CW metricname +is expected to be a valid performance metrics name (see +.BR pmns (5) +for more details). +.PP +The input may include +.BR sh -style +comment lines, i.e. with a `\f3#\f1' as the first non-blank character of a +line, and these are translated on output to either single line or multi-line C +comments in the K&R style. For example, the input: + +.PP +.ft CW +.nf +.in +0.5i +# leading block of multi-line comments +# initialization group +foo { + a.b.c ONE + d.e.f.g TWO + # embedded block of multi-lines + # comments and boring pad text + xx.yy.zz THREE +} + +# trailing single line comment +.in +.fi +.ft 1 +.PP + +Produces the output: +.PP +.ft CW +.nf +.in +0.5i +/* + * leading block of multi-line comments + * initialization group + */ +char *foo[] = { +#define ONE 0 + "a.b.c", +#define TWO 1 + "d.e.f.g", +/* + * embedded block of multi-lines + * comments and boring pad text + */ +#define THREE 2 + "xx.yy.zz", + +}; + + +/* trailing single line comment */ +.in +.fi +.ft 1 +.SH EXAMPLE +For brevity we have removed the error handling code, and assumed the chosen +metrics do not have multiple values. +.PP +The input file +.PP +.ft CW +.nf +.in +0.5i +mystats { + kernel.percpu.cpu.idle IDLE + kernel.percpu.cpu.sys SYS + kernel.percpu.cpu.user USER + hinv.ncpu NCPU +} +.in +.fi +.ft 1 +.PP +produces the following C code, suitable for +.BR #include -ing +.PP +.ft CW +.nf +.in +0.5i +/* + * Performance Metrics Name Space Map + * Built by pmgenmap from the file + * mystats.metrics + * on Wed Dec 28 19:44:17 EST 1994 + * + * Do not edit this file! + */ + +char *mystats[] = { +#define IDLE 0 + "kernel.percpu.cpu.idle", +#define SYS 1 + "kernel.percpu.cpu.sys", +#define USER 2 + "kernel.percpu.cpu.user", +#define NCPU 3 + "hinv.ncpu", + +}; +.in +.fi +.ft 1 +.PP +Using the code generated by +.BR pmgenmap , +we are now able to easily obtain metrics from the Performance Metrics Collection +Subsystem (PMCS) as follows: + +.PP +.ft CW +.nf +.in +0.5i +#define MAX_PMID 4 + + int trip = 0; + int numpmid = sizeof(mystats)/sizeof(mystats[0]); + double duration; + pmResult *resp; + pmResult *prev; + pmID pmidlist[MAX_PMID]; + + pmNewContext(PM_CONTEXT_HOST, "localhost"); + pmLookupName(numpmid, mystats, pmidlist); + pmFetch(numpmid, pmidlist, &resp); + + printf("%d CPUs: %d usr %d sys %d idle\n", + resp->vset[NCPU]->vlist[0].value.lval, + resp->vset[USER]->vlist[0].value.lval, + resp->vset[SYS]->vlist[0].value.lval, + resp->vset[IDLE]->vlist[0].value.lval); +.in +.fi +.ft 1 +.PP +Some calls to ensure portability have been removed from the code above for the +sake of clarity \- the example above should not be used as a template for +programming. In particular, the raw values of the metrics were used when +.BR pmLookupDesc (3) +should have been called to determine the semantics of each metric. +.PP +More complete examples that demonstrate the use of +.B pmgenmap +which may be used as a basis for program development are included in the +PCP demos, e.g. +.IR $PCP_DEMOS_DIR/pmclient . +.SH FILES +.PD 0 +.TP 10 +.BI $PCP_VAR_DIR/pmns/ * +default PMNS specification files +.PD +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.I /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). +.SH SEE ALSO +.BR cpp (1), +.BR PMAPI (3), +.BR pmFetch (3), +.BR pmLookupName (3), +.BR pmNewContext (3), +.BR pcp.conf (5), +.BR pcp.env (5) +and +.BR pmns (5). diff --git a/man/man1/pmgetopt.1 b/man/man1/pmgetopt.1 new file mode 100644 index 0000000..0302861 --- /dev/null +++ b/man/man1/pmgetopt.1 @@ -0,0 +1,218 @@ +'\"! tbl | mmdoc +'\"macro stdmacro +.\" +.\" Copyright (c) 2014 Red Hat. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.TH PMGETOPT 1 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmgetopt\f1 \- Performance Co-Pilot shell script option parser +.SH SYNOPSIS +\f3$PCP_BINADM_DIR/pmgetopt\f1 +[\f3\-c\f1|\f3\-\-config\f1 \f2file\f1] +[\f3\-p\f1|\f3\-\-progname\f1 \f2name\f1] +[\f3\-u\f1|\f3\-\-usage\f1] +[\f3\-\-\f1] +[\f2parameters\f1] +.SH DESCRIPTION +.de EX +.in +0.5i +.ie t .ft CB +.el .ft B +.ie t .sp .5v +.el .sp +.ta \\w' 'u*8 +.nf +.. +.de EE +.fi +.ie t .sp .5v +.el .sp +.ft R +.in +.. +.B pmgetopt +is used to perform command line option parsing for shell scripts +used in the Performance Co-Pilot (PCP toolkit). +It is also used to generate usage messages for those scripts. +.PP +The parameters given to +.B pmgetopt +take two forms: initially, options specific to +.B pmgetopt +itself are passed in, and terminated using the \-\- mechanism. +Thereafter, all of the parameters passed into the shell script +should be passed (usually this is simply the "$@" variable). +.PP +The options specific to +.B pmgetopt +are as follows: +.TP 5 +.BR \-c , \-\-config +A configuration +.I file +in the format described below is passed to +.B pmconfig +using this option. +If this option is omitted, then +.B pmconfig +will read its configuration from the standard input stream. +.TP +.BR \-p , \-\-progname +When parsing the calling shell scripts parameters, error and usage +messages will contain the given program +.I name +rather than referring to +.B pmgetopt +itself as the source of the error. +.TP +.BR \-u , \-\-usage +A usage message appropriate for the calling shell script to +present as its own can be generated using the +option. +.PP +.B pmgetopt +parses the given parameters, and produces output in a format +suitable for sourcing in the calling shell script. +When both short and long forms of an argument are allowed by +the specification, +.B pmgetopt +will always indicate the short form for simpler shell processing. +If arguments are presented that do not match the configuration, +a request for a usage message (\-\?) will be generated for the +calling script to respond to. +Any non-option parameters will be echoed back to the calling +script preceded by the double-hyphen delimiter. Thus a script +should stop handling options when this delimiter is detected, +and begin the handling of any non-option arguments. +.PP +Unlike with the shell built-in +.I getopt +command, variables like $OPTARG are +not set and the calling script will typically employ use of the +shell built-in +.IR eval , +.I set +and positional +.I shift +commands to ensure option processing occurs correctly. +.SH CONFIGURATION +The configuration format used by +.B pmgetopt +is intended to closely reflect the usage message which would be +generated in the presence of invalid arguments (or the +.BR \-? , \-\-help +option). +.PP +There are primarily two types of configuration line \- commands +and options. +Commands allow metadata to be passed into the option processing +process, and options are the allowable command line options that +the shell script will accept. +Command lines are preceded by the hash character, whereas option +lines will always begin with a hyphen (either single or double). +Any other line in the configuration, which may include usage headers +or descriptive text, has no impact on the option parsing and will be +copied unmodified into the usage message. +.PP +The set of commands is: +.I getopt +(provide short-argument option specification manually, +if not present this will be generated from the options presented), +.I usage +(provide short one-line summary used at the head of the +usage message, which will be prefixed by the +.I progname +before reporting), and +.I end +which informs +.B pmgetopt +to stop processing further commands and options \- any subsequent +text encountered will be simply appended to the usage message. +.PP +A short-hand notation exists for each of the standard PCP options, +as described in +.BR PCPIntro (1). +If any of these options (e.g \f3\-\-host\f1) appears as a single word on +any line, it will be transformed into the appropriate option for the +shell script, including all metadata about that option (whether it +accepts an argument, both short and long option forms, and so on). +.PP +Use of the equals symbol ("=") indicates the presence of a required +argument to any option, for both short and long forms. +Any non-standard option must be accompanied by a non-empty description +of that argument. +.SH EXAMPLES +As an example, the following is a valid configuration: +.EX +# Usage: [options] node... + +Options: + --archive + -d, --delay pause between updates for archive replay + --host + --interval + -i=INST, --insts=INST comma-separated metrics instance list + -r output raw counters (no rate conversion) + --width=N set the width of each column of output + --timezone + --help +.EE +.PP +This configuration will produce the following usage message, +when run as shown. +.EX +$ pmgetopt --usage --progname=clusterstat -- "$@" +Usage: clusterstat [options] node... + +Options: + -a FILE, --archive=FILE + metrics source is a PCP log archive + -d, --delay pause between updates for archive replay + -h HOST, --host=HOST metrics source is PMCD on host + -t DELTA, --interval=DELTA + sampling interval + -i INST, --insts=INST comma-separated metrics instance list + -r output raw counters (no rate conversion) + --width=N set the width of each column of output + -Z TZ, --timezone=TZ set reporting timezone + -?, --help show this usage message and exit +.EE +.PP +Several examples of +.B pmgetopt +use form part of the PCP toolkit, in particular the +.BR pcp (1) +and +.BR pmlogmv (1) +scripts provide good reference examples. +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.I /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). +.SH SEE ALSO +.BR pcp (1), +.BR pmlogmv (1), +.BR pmgetopt_r (3), +.BR pcp.conf (5) +and +.BR pcp.env (5). diff --git a/man/man1/pmhostname.1 b/man/man1/pmhostname.1 new file mode 100644 index 0000000..77dec64 --- /dev/null +++ b/man/man1/pmhostname.1 @@ -0,0 +1,76 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMHOSTNAME 1 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmhostname\f1 \- report hostname +.\" literals use .B or \f3 +.\" arguments use .I or \f2 +.SH SYNOPSIS +.B $PCP_BINADM_DIR/pmhostname +[\fIhostname\fR] +.SH DESCRIPTION +.B pmhostname +reports the name of the host +.I hostname +as returned by +.BR gethostbyname (3N). +.PP +If +.I hostname +is not specified, then the local host name +is retrieved using +.BR gethostname (2) +and this is than passed to +.BR gethostbyname (3N). +.PP +.B pmhostname +provides a service for shell scripts that +mimics the logic formerly used by Performance Co-Pilot applications +when trying to determine the official name of a host. PCP applications +no longer use DNS-based heuristics, and therefore this command is +.IR deprecated . +.PP +If +.BR gethostbyname (3N) +fails, the input host name (either +.I hostname +or the result from calling +.BR gethostname (2)) +is reported. +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.I /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). +.SH SEE ALSO +.BR named (1), +.BR nsd (1), +.BR nslookup (1), +.BR gethostname (2), +.BR gethostbyname (3N), +.BR pcp.conf (5), +.BR pcp.env (5) +and +.BR resolver (5). diff --git a/man/man1/pmie.1 b/man/man1/pmie.1 new file mode 100644 index 0000000..1400b10 --- /dev/null +++ b/man/man1/pmie.1 @@ -0,0 +1,1161 @@ +'\"! tbl | mmdoc +'\"macro stdmacro +.\" +.\" Copyright (c) 2000 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMIE 1 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmie\f1 \- inference engine for performance metrics +.SH SYNOPSIS +\f3pmie\f1 +[\f3\-bCdefHVvWxz\f1] +[\f3\-A\f1 \f2align\f1] +[\f3\-a\f1 \f2archive\f1] +[\f3\-c\f1 \f2filename\f1] +[\f3\-h\f1 \f2host\f1] +[\f3\-l\f1 \f2logfile\f1] +[\f3\-j\f1 \f2stompfile\f1] +[\f3\-n\f1 \f2pmnsfile\f1] +[\f3\-O\f1 \f2offset\f1] +[\f3\-S\f1 \f2starttime\f1] +[\f3\-T\f1 \f2endtime\f1] +[\f3\-t\f1 \f2interval\f1] +[\f3\-U\f1 \f2username\f1] +[\f3\-Z\f1 \f2timezone\f1] +[\f2filename ...\f1] +.SH DESCRIPTION +.B pmie +accepts a collection of arithmetic, logical, and rule expressions to be +evaluated at specified frequencies. The base data for the expressions +consists of performance metrics values delivered in real-time +from any host +running the Performance Metrics Collection Daemon (PMCD), or using historical +data from Performance Co-Pilot (PCP) archive logs. +.P +As well as computing arithmetic and logical values, +.B pmie +can execute actions (popup alarms, write system log messages, and launch +programs) in response to specified conditions. Such actions are +extremely useful in detecting, monitoring and correcting performance +related problems. +.P +The expressions to be evaluated are read from +configuration files specified by one or more +.I filename +arguments. In the absence of any +.IR filename , +expressions are read from standard input. +.P +A description of the command line options specific to +.B pmie +follows: +.TP 5 +.B \-a +.I archive +is the base name of a PCP archive log written by +.BR pmlogger (1). +Multiple instances of the +.B \-a +flag may appear on the command line to specify a set of archives. +In this case, it is required that only one archive be present for any +one host. +Also, any explicit host names occurring in a +.B pmie +expression must match the host name recorded in one of the archive labels. +In the case of multiple archives, timestamps recorded in the archives are +used to ensure temporal consistency. +.TP +.B \-b +Output will be line buffered and standard output is attached to standard +error. This is most useful for background execution in conjunction with +the +.B \-l +option. +The +.B \-b +option is always used for +.B pmie +instances launched from +.BR pmie_check (1). +.TP +.B \-C +Parse the configuration file(s) and exit before performing any evaluations. +Any errors in the configuration file are reported. +.TP +.B \-c +An alternative to specifying +.I filename +at the end of the command line. +.TP +.B \-d +Normally +.B pmie +would be launched as a non-interactive process to monitor and manage the +performance of one or more hosts. +Given the +.B \-d +flag however, execution is interactive and the user is presented +with a menu of options. +Interactive mode is useful mainly for debugging new expressions. +.TP +.B \-e +When used with +.BR \-V , +.B \-v +or +.BR \-W , +this option +forces timestamps to be reported with each expression. The timestamps +are in +.BR ctime (3) +format, enclosed in parenthesis and appear after the expression name and before the +expression value, e.g. +.nf + expr_1 (Tue Feb 6 19:55:10 2001): 12 +.fi +.TP +.B \-f +If the +.B \-l +option is specified and there is no +.B \-a +option (ie. real-time monitoring) then +.B pmie +is run as a daemon in the background +(in all other cases foreground is the default). +The +.B \-f +option forces +.B pmie +to be run in the foreground, independent of any other options. +.TP +.B \-H +The default hostname written to the stats file will not be looked up via +.BR gethostbyname (3), +rather it will be written as-is. +This option can be useful when host name aliases are in use at a site, +and the logical name is more important than the physical host name. +.TP +.B \-h +By default performance data is fetched from the local host (in real-time mode) +or the host for the first named archive on the command line +(in archive mode). The \f2host\f1 argument overrides this default. +It does not override hosts explicitly named in the expressions +being evaluated. +.TP +.B \-l +Standard error is sent to +.IR logfile . +.TP +.B \-j +An alternative STOMP protocol configuration is loaded from +.IR stompfile . +If this option is not used, and the +.I stomp +action is used in any rule, the default location +.I $PCP_SYSCONF_DIR/pmie/config/stomp +will be used. +.TP +.B \-n +An alternative Performance Metrics Name Space (PMNS) is loaded from the file +.IR pmnsfile . +.TP +.B \-t +The +.I interval +argument follows the syntax described in +.BR PCPIntro (1), +and in the simplest form may be an unsigned integer (the implied +units in this case are seconds). +The value is used to determine the sample interval for +expressions that do not explicitly set their sample interval using +the +.B pmie +variable \f(CWdelta\f1 described below. +The default is 10.0 seconds. +.TP +\f3\-U\f1 \f2username\f1 +User account under which to run +.BR pmie . +The default is the current user account for interactive use. +When run as a daemon, the unprivileged "pcp" account is used +in current versions of PCP, but in older versions the superuser +account ("root") was used by default. +.TP +.B \-v +Unless one of the verbose options +.BR \-V , +.B \-v +or +.B \-W +appears on the command line, expressions are +evaluated silently, the only output is as a result of any actions +being executed. In the verbose mode, specified using the +.B \-v +flag, the value of each expression is printed as it is +evaluated. +The values are in canonical units; +bytes in the dimension of ``space'', seconds in the dimension of ``time'' +and events in the dimension of ``count''. +See +.BR pmLookupDesc (3) +for details of the supported dimension and scaling mechanisms +for performance metrics. +The verbose mode is useful in monitoring the value of given +expressions, evaluating derived performance metrics, +passing these values on to other tools for further processing +and in debugging new expressions. +.TP +.B \-V +This option has the same effect as the +.B \-v +option, except that the name of the host and instance +(if applicable) are printed as well as expression values. +.TP +.B \-W +This option has the same effect as the +.B \-V +option described above, except that for boolean expressions, +only those names and values that make the expression true are printed. +These are the same names and values accessible to rule actions as the +%h, %i and %v bindings, as described below. +.TP +.B \-x +Execute in domain agent mode. This mode is used within the Performance +Co-Pilot product to derive values for summary metrics, see +.BR pmdasummary (1). +Only restricted functionality +is available in this mode +(expressions with actions may +.B not +be used). +.TP +.B \-Z +Change the reporting timezone to +.I timezone +in the format of the environment variable +.B TZ +as described in +.BR environ (5). +.TP +.B \-z +Change the reporting timezone to the timezone of the host that is the source +of the performance metrics, as identified via either the +.B \-h +option or the first named archive (as described above for the +.B \-a +option). +.P +The +.BR \-S , +.BR \-T , +.BR \-O , +and +.B \-A +options may be used to define a time window to restrict the +samples retrieved, set an initial origin within the time window, +or specify a ``natural'' alignment of the sample times; refer to +.BR PCPIntro (1) +for a complete description of these options. +.P +Output from +.B pmie +is directed to standard output and standard error as follows: +.TP 5 +.B stdout +Expression values printed in the verbose +.B \-v +mode and the output of +.B print +actions. +.TP +.B stderr +Error and warning messages for any syntactic or semantic problems during +expression parsing, and any semantic or performance metrics availability +problems during expression evaluation. +.SH EXAMPLES +The following example expressions demonstrate some of the capabilities +of the inference engine. +.P +The directory +.I $PCP_DEMOS_DIR/pmie +contains a number of other annotated examples of +.B pmie +expressions. +.P +The variable +.ft CW +delta +.ft 1 +controls expression evaluation frequency. Specify that subsequent expressions +be evaluated once a second, until further notice: +.P +.ft CW +.nf +.in +0.5i +delta = 1 sec; +.in +.fi +.ft 1 +.P +If the total context switch rate exceeds 10000 per second per CPU, +then display an alarm notifier: +.P +.ft CW +.nf +.in +0.5i +kernel.all.pswitch / hinv.ncpu > 10000 count/sec +-> alarm "high context switch rate %v"; +.in +.fi +.ft 1 +.P +If the high context switch rate is sustained for 10 consecutive samples, +then launch +.BR top (1) +in an +.BR xwsh (1G) +window to monitor processes, but do this at most once every 5 minutes: +.P +.ft CW +.nf +.in +0.5i +all_sample ( + kernel.all.pswitch @0..9 > 10 Kcount/sec * hinv.ncpu +) -> shell 5 min "xwsh \-e 'top'"; +.in +.fi +.ft 1 +.P +The following rules are evaluated once every 20 seconds: +.P +.ft CW +.nf +.in +0.5i +delta = 20 sec; +.in +.fi +.ft 1 +.P +If any disk is performing +more than 60 I/Os per second, then print a message identifying +the busy disk to standard output and +launch +.BR dkvis (1): +.P +.ft CW +.nf +.in +0.5i +some_inst ( + disk.dev.total > 60 count/sec +) -> print "busy disks:" " %i" & + shell 5 min "dkvis"; +.in +.fi +.ft 1 +.P +Refine the preceding rule to apply only between the hours of 9am and 5pm, +and to require 3 of 4 consecutive samples to exceed the threshold before +executing the action: +.P +.ft CW +.nf +.in +0.5i +$hour >= 9 && $hour <= 17 && +some_inst ( + 75 %_sample ( + disk.dev.total @0..3 > 60 count/sec + ) +) -> print "disks busy for 20 sec:" " [%h]%i"; +.in +.fi +.ft 1 +.P +The following two rules are evaluated once every 10 minutes: +.P +.ft CW +.nf +.in +0.5i +delta = 10 min; +.in +.fi +.ft 1 +.P +If either the / or the /usr filesystem is more than 95% full, +display an alarm popup, but not if it has already been displayed +during the last 4 hours: +.P +.ft CW +.nf +.in +0.5i +filesys.free #'/dev/root' / + filesys.capacity #'/dev/root' < 0.05 +-> alarm 4 hour "root filesystem (almost) full"; + +filesys.free #'/dev/usr' / + filesys.capacity #'/dev/usr' < 0.05 +-> alarm 4 hour "/usr filesystem (almost) full"; +.in +.fi +.ft 1 +.P +The following rule requires a machine that supports the PCP environment metrics. +If the machine environment temperature rises more than 2 degrees over a +10 minute interval, write an entry in the system log: +.P +.ft CW +.nf +.in +0.5i +environ.temp @0 - environ.temp @1 > 2 +-> alarm "temperature rising fast" & + syslog "machine room temperature rise alarm"; +.in +.fi +.ft 1 +.P +And something interesting if you have performance problems +with your Oracle database: +.P +.ft CW +.nf +.in +0.5i +// back to 30sec evaluations +delta = 30 sec; +db = "oracle.ptg1"; +host = ":moomba.melbourne.sgi.com"; +lru = "#'cache buffers lru chain'"; +gets = "$db.latch.gets $host $lru"; +total = "$db.latch.gets $host $lru + + $db.latch.misses $host $lru + + $db.latch.immisses $host $lru"; + +$total > 100 && $gets / $total < 0.2 +-> alarm "high lru latch contention"; +.in +.fi +.ft 1 +.P +The following \f(CBruleset\fR will emit exactly one message +depending on the availability and value of the 1-minute load +average. +.P +.ft CW +.nf +.in +0.5i +delta = 1 minute; +ruleset + kernel.all.load #'1 minute' > 10 * hinv.ncpu -> + print "extreme load average %v" +else kernel.all.load #'1 minute' > 2 * hinv.ncpu -> + print "moderate load average %v" +unknown -> + print "load average unavailable" +otherwise -> + print "load average OK" +; +.in +.fi +.ft 1 +.SH QUICK START +The +.B pmie +specification language is powerful and large. +.P +To expedite rapid development of +.B pmie +rules, the +.BR pmieconf (1) +tool provides a facility for generating a +.B pmie +configuration file from a set of generalized +.B pmie +rules. +The supplied set of rules covers +a wide range of performance scenarios. +.P +The +.I "Performance Co-Pilot User's and Administrator's Guide" +provides a detailed tutorial-style chapter covering +.BR pmie . +.SH EXPRESSION SYNTAX +This description is terse and informal. +For a more comprehensive description see the +.IR "Performance Co-Pilot User's and Administrator's Guide" . +.P +A +.B pmie +specification is a sequence of semicolon terminated expressions. +.P +Basic operators are modeled on the arithmetic, relational and Boolean +operators of the C programming language. +Precedence rules are as expected, although the use of parentheses +is encouraged to enhance readability and remove ambiguity. +.P +Operands are performance metric names +(see +.BR pmns (5)) +and the normal literal constants. +.P +Operands involving performance metrics may produce sets of values, as a +result of enumeration in the dimensions of +.BR hosts , +.B instances +and +.BR time . +Special qualifiers may appear after a performance metric name to +define the enumeration in each dimension. For example, +.P +.in +4n +.ft CW +kernel.percpu.cpu.user :foo :bar #cpu0 @0..2 +.ft R +.in +.P +defines 6 values corresponding to the time spent executing in +user mode on CPU 0 on the hosts ``foo'' and ``bar'' over the last +3 consecutive samples. +The default interpretation in the absence of +.B : +(host), +.B # +(instance) and +.B @ +(time) qualifiers is all instances at the most recent sample time +for the default source of PCP performance metrics. +.P +Host and instance names that do not follow the rules for variables +in programming languages, ie. alphabetic optionally followed by +alphanumerics, should be enclosed in single quotes. +.P +Expression evaluation follows the law of ``least surprises''. +Where performance metrics have the semantics of a counter, +.B pmie +will automatically convert to a rate based upon consecutive samples +and the time interval between these samples. +All expressions are evaluated in double precision, and where +appropriate, automatically +scaled into canonical units of ``bytes'', ``seconds'' and ``counts''. +.P +A +.B rule +is a special form of expression that specifies a condition or logical +expression, a special operator (\c +.BR \-> ) +and actions to be performed when the condition is found to be true. +.P +The following table summarizes the basic +.B pmie +operators: +.P +.ne 12v +.TS +box,center; +c | c +lf(CW) | l. +Operators Explanation +_ ++ \- * / Arithmetic +< <= == >= > != Relational (value comparison) +! && || Boolean +-> Rule +\f(CBrising\fR Boolean, false to true transition +\f(CBfalling\fR Boolean, true to false transition +\f(CBrate\fR Explicit rate conversion (rarely required) +.TE +.P +Aggregate operators may be used to aggregate or summarize along +one dimension of a set-valued expression. +The following aggregate operators map from a logical expression to +a logical expression of lower dimension. +.P +.ne 16v +.TS +box,center; +cw(2.4i) | c | cw(2.4i) +lf(CB) | l | l. +Operators Type Explanation +_ +T{ +.ad l +some_inst +.br +some_host +.br +some_sample +T} Existential T{ +.ad l +True if at least one set member is true in the associated dimension +T} +_ +T{ +.ad l +all_inst +.br +all_host +.br +all_sample +T} Universal T{ +.ad l +True if all set members are true in the associated dimension +T} +_ +T{ +.ad l +\f(CON\f(CB%_inst +.br +\f(CON\f(CB%_host +.br +\f(CON\f(CB%_sample\fR +T} Percentile T{ +.ad l +True if at least \fIN\fP percent of set members are true in the associated dimension +T} +.TE +.P +The following instantial operators may be used to filter or limit a +set-valued logical expression, based on regular expression matching +of instance names. The logical expression must be a set involving +the dimension of instances, and the regular expression is of the +form used by +.BR egrep (1) +or the Extended Regular Expressions of +.BR regcomp (3G). +.P +.ne 12v +.TS +box,center; +c | cw(4i) +lf(CB) | l. +Operators Explanation +_ +match_inst T{ +.ad l +For each value of the logical expression that is ``true'', the +result is ``true'' if the associated instance name matches the +regular expression. Otherwise the result is ``false''. +T} +_ +nomatch_inst T{ +.ad l +For each value of the logical expression that is ``true'', the +result is ``true'' if the associated instance name does +\fBnot\fP match the +regular expression. Otherwise the result is ``false''. +T} +.TE +.P +For example, the expression below will be ``true'' for disks +attached to controllers 2 or 3 performing more than 20 operations per second: +.ft CW +.nf +.in +0.5i +match_inst "^dks[23]d" disk.dev.total > 20; +.in +.fi +.ft 1 +.P +The following aggregate operators map from an arithmetic expression to +an arithmetic expression of lower dimension. +.P +.ne 20v +.TS +box,center; +cw(2.4i) | c | cw(2.4i) +lf(CB) | l | l. +Operators Type Explanation +_ +T{ +.ad l +min_inst +.br +min_host +.br +min_sample +T} Extrema T{ +.ad l +Minimum value across all set members in the associated dimension +T} +_ +T{ +.ad l +max_inst +.br +max_host +.br +max_sample +T} Extrema T{ +.ad l +Maximum value across all set members in the associated dimension +T} +_ +T{ +.ad l +sum_inst +.br +sum_host +.br +sum_sample +T} Aggregate T{ +.ad l +Sum of values across all set members in the associated dimension +T} +_ +T{ +.ad l +avg_inst +.br +avg_host +.br +avg_sample +T} Aggregate T{ +.ad l +Average value across all set members in the associated dimension +T} +.TE +.P +The aggregate operators \f(CWcount_inst\fR, \f(CWcount_host\fR and +\f(CWcount_sample\fR map from a logical expression to an arithmetic +expression of lower dimension by counting the number of set members +for which the expression is true in the associated dimension. +.P +For action rules, the following actions are defined: +.TS +box,center; +c | c +lf(CB) | l. +Operators Explanation +_ +alarm Raise a visible alarm with \fBxconfirm\f1(1) +print Display on standard output +shell Execute with \fBsh\fR(1) +stomp Send a STOMP message to a JMS server +syslog Append a message to system log file +.TE +.P +Multiple actions may be separated by the \f(CW&\fR and \f(CW|\fR +operators to specify respectively sequential execution (both +actions are executed) and alternate execution (the second action +will only be executed if the execution of the first action returns +a non-zero error status. +.P +Arguments to actions are an optional suppression time, and then +one or more expressions (a string is an expression in this context). +Strings appearing as arguments to an action may include the following +special selectors that will be replaced at the time the action +is executed. +.TP 4n +\f(CB%h\fR +Host(s) that make the left-most top-level expression in the +condition true. +.TP +\f(CB%i\fR +Instance(s) that make the left-most top-level expression in the +condition true. +.TP +\f(CB%v\fR +One value from the left-most top-level expression in the +condition for each host and instance pair that +makes the condition true. +.P +Note that expansion of the special selectors is done by repeating the +whole argument once for each unique binding to any of the +qualifying special selectors. +For example if a rule were true for the host +.B mumble +with instances +.B grunt +and +.BR snort , +and for host +.B fumble +the instance +.B puff +makes the rule true, then the action +.ft CW +.nf +.in +0.5i +\&... +-> shell myscript "Warning: %h:%i busy "; +.in +.fi +.ft 1 +will execute +.B myscript +with the argument string "Warning: mumble:grunt busy Warning: mumble:snort busy Warning: fumble:puff busy". +.P +By comparison, if the action +.ft CW +.nf +.in +0.5i +\&... +-> shell myscript "Warning! busy:" " %h:%i"; +.in +.fi +.ft 1 +were executed under the same circumstances, then +.B myscript +would be executed with the argument string "Warning! busy: mumble:grunt mumble:snort fumble:puff". +.P +The semantics of the expansion of the special selectors leads to a +common usage pattern in an action, where one argument is a constant (contains no +special selectors) the second argument contains the desired +special selectors with minimal separator characters, and +an optional third argument provides a constant postscript (e.g. to terminate +any argument quoting from the first argument). +If necessary +post-processing (eg. in +.BR myscript ) +can provide the necessary enumeration over each unique expansion +of the string containing just the special selectors. +.P +For complex conditions, the bindings to these selectors +is not obvious. +It is strongly recommended that +.B pmie +be used in +the debugging mode (specify the +.B \-W +command line option in particular) during rule development. +.SH BOOLEAN EXPRESSIONS +.B pmie +expressions that have the semantics of a Boolean, e.g. +\f(CWfoo.bar > 10\fR +or +\f(CBsome_inst\f(CW ( my.table < 0 ) +.ft R +are assigned the values \f(CBtrue\fR or \f(CBfalse\fR or \f(CBunknown\fR. +A value is \f(CBunknown\fR if one or more of the underlying metric values +is unavailable, e.g. +.BR pmcd (1) +on the host cannot be contacted, the metric is not in the PCP archive, +no values are currently available, insufficient values have been fetched +to allow a rate converted value to be computed or insufficient values have +been fetched to instantiate the required number of samples in the +temporal domain. +.PP +Boolean operators follow the normal rules of Kleene logic (aka 3-valued +logic) when combining values that include \f(CBunknown\fR: +.TS +box,center; +c s|c s s +^ s|c s s +^ s|c|c|c +c|c|c|c|c +^|c|c|c|c. +A \f(CBand\fR B B + _ + \f(CBtrue\fR \f(CBfalse\fR \f(CBunknown\fR +_ +A \f(CBtrue\fR \f(CBtrue\fR \f(CBfalse\fR \f(CBunknown\fR + _ _ _ _ + \f(CBfalse\fR \f(CBfalse\fR \f(CBfalse\fR \f(CBfalse\fR + _ _ _ _ + \f(CBunknown\fR \f(CBunknown\fR \f(CBfalse\fR \f(CBunknown\fR +.TE +.TS +box,center; +c s|c s s +^ s|c s s +^ s|c|c|c +c|c|c|c|c +^|c|c|c|c. +A \f(CBor\fR B B + _ +B \f(CBtrue\fR \f(CBfalse\fR \f(CBunknown\fR +_ +A \f(CBtrue\fR \f(CBtrue\fR \f(CBtrue\fR \f(CBtrue\fR + _ _ _ _ + \f(CBfalse\fR \f(CBtrue\fR \f(CBfalse\fR \f(CBunknown\fR + _ _ _ _ + \f(CBunknown\fR \f(CBtrue\fR \f(CBunknown\fR \f(CBunknown\fR +.TE +.TS +box,center; +c|c. +A \f(CBnot\fR A +_ +\f(CBtrue\fR \f(CBfalse\fR +_ +\f(CBfalse\fR \f(CBtrue\fR +_ +\f(CBunknown\fR \f(CBunknown\fR +.TE +.SH RULESETS +The \f(CBruleset\fR clause is used to define a set of rules and +actions that are evaluated in order until some action is executed, +at which point the remaining rules and actions are skipped until +the \f(CBruleset\fR is again scheduled for evaluation. +The keyword \f(CBelse\fR is used to separate rules. +After one or more regular rules (with a predicate and an action), a +\f(CBruleset\fR may include an optional +.br +.ti +0.5i +\f(CBunknown\fR -> action +.br +clause, optionally followed by a +.br +.ti +0.5i +\f(CBotherwise\fR -> action +.br +clause. +.PP +If all of the predicates in the rules evaluate to \f(CBunknown\fR and +an \f(CBunknown\fR clause has been specified then action associated +with the \f(CBunknown\fR clause will be executed. +.PP +If no rule predicate is \f(CBtrue\fR and the \f(CBunknown\fR action +is either not specified or not +executed and an \f(CBotherwise\fR clause has been specified, +then the action associated with the \f(CBotherwise\fR clause will be executed. +.SH SCALE FACTORS +Scale factors may be appended to arithmetic expressions and force +linear scaling of the value to canonical units. Simple scale factors +are constructed from the keywords: +\f(CBnanosecond\fR, \f(CBnanosec\fR, \f(CBnsec\f1, +\f(CBmicrosecond\fR, \f(CBmicrosec\fR, \f(CBusec\f1, +\f(CBmillisecond\fR, \f(CBmillisec\fR, \f(CBmsec\f1, +\f(CBsecond\fR, \f(CBsec\fR, \f(CBminute\fR, \f(CBmin\fR, \f(CBhour\f1, +\f(CBbyte\fR, \f(CBKbyte\fR, \f(CBMbyte\fR, \f(CBGbyte\fR, \f(CBTbyte\f1, +\f(CBcount\fR, \f(CBKcount\fR and \f(CBMcount\fR, +and the operator \f(CW/\fR, for example ``\f(CBKbytes / hour\f1''. +.SH MACROS +Macros are defined using expressions of the form: +.P +.in +0.5i +\fIname\fR = \fIconstexpr\f1; +.in +.P +Where +.I name +follows the normal rules +for variables +in programming languages, ie. alphabetic optionally followed by +alphanumerics. +.I constexpr +must be a constant expression, either a string +(enclosed in double quotes) or an arithmetic expression optionally +followed by a scale factor. +.P +Macros are expanded when their name, prefixed by a dollar (\f(CW$\fR) +appears in an expression, and macros may be nested within a +.I constexpr +string. +.P +The following reserved macro names are understood. +.TP 10n +\f(CBminute\f1 +Current minute of the hour. +.TP +\f(CBhour\f1 +Current hour of the day, in the range 0 to 23. +.TP +\f(CBday\f1 +Current day of the month, in the range 1 to 31. +.TP +\f(CBmonth\f1 +Current month of the year, in the range 0 (January) to 11 (December). +.TP +\f(CByear\f1 +Current year. +.TP +\f(CBday_of_week\f1 +Current day of the week, in the range 0 (Sunday) to 6 (Saturday). +.TP +\f(CBdelta\f1 +Sample interval in effect for this expression. +.P +Dates and times are presented in the +reporting time zone (see description of +.B \-Z +and +.B \-z +command line options above). +.SH AUTOMATIC RESTART +It is often useful for +.B pmie +processes to be started and stopped when the local host is booted +or shutdown, or when they have been detected as no longer running +(when they have unexpectedly exited for some reason). +Refer to +.BR pmie_check (1) +for details on automating this process. +.SH EVENT MONITORING +It is common for production systems to be monitored in a central +location. +Traditionally on UNIX systems this has been performed by the system +log facilities \- see +.BR logger (1), +and +.BR syslogd (1). +On Windows, communication with the system event log is handled by +.BR pcp-eventlog (1). +.P +.B pmie +fits into this model when rules use the +.I syslog +action. +Note that if the action string begins with \-p (priority) and/or \-t (tag) +then these are extracted from the string and treated in the same way as in +.BR logger (1) +and +.BR pcp-eventlog (1). +.P +However, it is common to have other event monitoring frameworks also, +into which you may wish to incorporate performance events from +.BR pmie . +You can often use the +.I shell +action to send events to these frameworks, as they usually provide +their a program for injecting events into the framework from external +sources. +.P +A final option is use of the +.I stomp +(Streaming Text Oriented Messaging Protocol) action, which allows +.B pmie +to connect to a central JMS (Java Messaging System) server and send +events to the PMIE topic. +Tools can be written to extract these text messages and present them +to operations people (via desktop popup windows, etc). +Use of the +.I stomp +action requires a stomp configuration file to be setup, which specifies +the location of the JMS server host, port number, and username/password. +.P +The format of this file is as follows: +.P +.ft CW +.nf +.in +0.5i +host=messages.sgi.com # this is the JMS server (required) +port=61616 # and its listening here (required) +timeout=2 # seconds to wait for server (optional) +username=joe # (required) +password=j03ST0MP # (required) +topic=PMIE # JMS topic for pmie messages (optional) +.in +.fi +.ft 1 +.P +The timeout value specifies the time (in seconds) that +.B pmie +should wait for acknowledgements from the JMS server after +sending a message (as required by the STOMP protocol). +Note that on startup, +.B pmie +will wait indefinitely for a connection, and will not +begin rule evaluation until that initial connection has +been established. +Should the connection to the JMS server be lost at any +time while +.B pmie +is running, +.B pmie +will attempt to reconnect on each subsequent truthful +evaluation of a rule with a +.I stomp +action, but not more than once per minute. +This is to avoid contributing to network congestion. +In this situation, where the STOMP connection to the JMS server +has been severed, the +.I stomp +action will return a non-zero error value. +.SH FILES +.PD 0 +.TP 10 +.BI $PCP_DEMOS_DIR/pmie/ * +annotated example rules +.TP +.BI $PCP_VAR_DIR/pmns/ * +default PMNS specification files +.TP +.BI $PCP_TMP_DIR/pmie +.B pmie +maintains files in this directory to identify the running +.B pmie +instances and to export runtime information about each instance \- this data +forms the basis of the pmcd.pmie performance metrics +.TP +.BI $PCP_PMIECONTROL_PATH +the default set of +.B pmie +instances to start at boot time \- refer to +.BR pmie_check (1) +for details +.TP +.BI $PCP_SYSCONF_DIR/pmie/ * +the predefined alarm action scripts (\c +.BR email , +.BR log , +.B popup +and +.BR syslog ), +the example action script (\c +.BR sample ) and +the concurrent action control file (\c +.BR control.master ). +.PD +.SH BUGS +The lexical scanner and parser will attempt to recover after an +error in the input expressions. +Parsing resumes after skipping input up to +the next semi-colon (;), however during this skipping +process the scanner is ignorant of comments and strings, so an +embedded semi-colon may cause parsing to resume at an unexpected +place. This behavior is largely benign, as until the initial +syntax error is corrected, +.B pmie +will not attempt any expression evaluation. +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.I /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). +.SH UNIX SEE ALSO +.BR logger (1). +.SH WINDOWS SEE ALSO +.BR pcp-eventlog (1). +.SH SEE ALSO +.BR PCPIntro (1), +.BR pmcd (1), +.BR pmdumplog (1), +.BR pmieconf (1), +.BR pmie_check (1), +.BR pminfo (1), +.BR pmlogger (1), +.BR pmval (1), +.BR PMAPI (3), +.BR pcp.conf (5) +and +.BR pcp.env (5). +.SH USER GUIDE +For a more complete description of the +.B pmie +language, refer to the +.BR "Performance Co-Pilot Users and Administrators Guide" . +This is available online from: +.in +4n +.nf +http://www.performancecopilot.org/doc/pcp-users-and-administrators-guide.pdf +.fi +.in -4n diff --git a/man/man1/pmie2col.1 b/man/man1/pmie2col.1 new file mode 100644 index 0000000..50112a5 --- /dev/null +++ b/man/man1/pmie2col.1 @@ -0,0 +1,135 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMIE2COL 1 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmie2col\f1 \- convert pmie output to multi-column format +.SH SYNOPSIS +\f3pmie2col\f1 +[\f3\-d\f1 \f2delimiter\f1] +[\f3\-p\f1 \f2precision\f1] +[\f3\-w\f1 \f2width\f1] +.de EX +.in +0.5i +.ie t .ft CB +.el .ft B +.ie t .sp .5v +.el .sp +.ta \\w' 'u*8 +.nf +.. +.de EE +.fi +.ie t .sp .5v +.el .sp +.ft R +.in +.. +.SH DESCRIPTION +.B pmie2col +is a simple tool that converts output from +.BR pmie (1) +into regular column format. Each column is 7 characters wide +(by default, may be changed with the +.B \-w +option) with a single space between columns. +That single space can be substituted with an alternate +delimiter using the +.B \-d +option (this is useful for importing the data into a spreadsheet, +for example). +.PP +The precision of the tabulated values from +.B pmie +can be specified with the +.B \-p +option (default is 2 decimal places). +This option can and will override any width setting in order to +present the requested precision. +.PP +The +.BR pmie (1) +configuration must follow these rules: +.IP (1) +Each +.BR pmie (1) +expression is of the form ``NAME = expr;''. +NAME will be used as the column heading, and must contain no white space, +although special characters can be escaped by enclosing NAME in single +quotes. +.IP (2) +The ``expr'' must be a valid +.BR pmie (1) +expression that produces a singular value. +.PP +In addition, +.BR pmie (1) +must be run with the +.B \-v +command line option. +.PP +It is also possible to use the +.B \-e +command line to +.BR pmie (1) +and output lines will be prefixed by a timestamp. +.SH EXAMPLE +.PP +Given this +.BR pmie (1) +configuration file +.IR (config) : +.EX +loadav = kernel.all.load #'1 minute'; +\&'%usr' = kernel.all.cpu.user; +\&'%sys' = kernel.all.cpu.sys; +\&'%wio' = kernel.all.cpu.wait.total; +\&'%idle' = kernel.all.cpu.idle; +\&'max-iops' = max_inst(disk.dev.total); +.EE +Then this command pipeline: +.EX +$ pmie \-v \-t 5 <config | pmie2col \-w 8 +.EE +Produces output like this: +.EX + loadav %usr %sys %wio %idle max-iops + 0.21 ? ? ? ? ? + 0.36 0.49 0.03 0.18 0.29 25.40 + 0.49 0.41 0.10 0.36 0.13 51.00 + 0.69 0.49 0.10 0.05 0.37 43.20 + 0.71 0.39 0.08 0.04 0.49 14.00 + 0.83 0.63 0.15 0.00 0.21 32.30 + 1.09 0.60 0.02 0.10 0.27 47.00 + 0.92 0.01 0.00 0.00 0.99 2.40 +.EE +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.I /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). +.SH SEE ALSO +.BR PCPIntro (1) +and +.BR pmie (1). diff --git a/man/man1/pmie_check.1 b/man/man1/pmie_check.1 new file mode 100644 index 0000000..bc81f0e --- /dev/null +++ b/man/man1/pmie_check.1 @@ -0,0 +1,336 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2013-2014 Red Hat. +.\" Copyright (c) 2000-2004 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMIE_CHECK 1 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmie_check\f1, +\f3pmie_daily\f1 \- administration of the Performance Co-Pilot inference engine +.SH SYNOPSIS +.B $PCP_BINADM_DIR/pmie_check +[\f3\-CNsV\f1] +[\f3\-c\f1 \f2control\f1] +.br +.B $PCP_BINADM_DIR/pmie_daily +[\f3\-NV\f1] +[\f3\-c\f1 \f2control\f1] +[\f3\-k\f1 \f2discard\f1] +[\f3\-m\f1 \f2addresses\f1] +[\f3\-x\f1 \f2compress\f1] +[\f3\-X\f1 \f2program\f1] +[\f3\-Y\f1 \f2regex\f1] +.br +.SH DESCRIPTION +This series of shell scripts and associated control files may be used to +create a customized regime of administration and management for the +Performance Co-Pilot (see +.BR PCPintro (1)) +inference engine, +.BR pmie (1). +.PP +.B pmie_daily +is intended to be run once per day, preferably in the early morning, as +soon after midnight as practicable. Its task is to rotate the log files +for the running +.B pmie +processes \- these files may grow without bound if the +``print'' action is used, or any other +.B pme +action writes to its stdout/stderr streams. +After some period, old +.B pmie +log files are discarded. +This period is 14 days by default, but may be changed using the +.B \-k +option. Two special values are recognized for the period (\c +.IR discard ), +namely +.B 0 +to keep no log files beyond the current one, and +.B forever +to prevent any log files being discarded. +.PP +Log files can optionally be compressed after some period (\c +.IR compress ), +to conserve disk space. This is particularly useful for large numbers of +.B pmie +processes under the control of +.BR pmie_check . +The +.B \-x +option specifies the number of days after which to compress archive data +files, and the +.B \-X +option specifies the program to use for compression \- by default this is +.BR xz (1). +Use of the +.B \-Y +option allows a regular expression to be specified causing files in +the set of files matched for compression to be omitted \- this allows +only the data file to be compressed, and also prevents the program from +attempting to compress it more than once. The default +.I regex +is "\.(meta|index|Z|gz|bz2|zip|xz|lzma|lzo|lz4)$" \- such files are +filtered using the +.B \-v +option to +.BR egrep (1). +.PP +Use of the +.B \-m +option causes +.B pmie_daily +to construct a summary of the log files generated for all monitored hosts +in the last 24 hours (lines matching `` OK '' are culled), and e-mail that +summary to the set of space-separated +.IR addresses . +.PP +.B pmie_check +may be run at any time, and is intended to check that the desired set +of +.BR pmie (1) +processes are running, and if not to re-launch any failed inference engines. +Use of the +.B \-s +option provides the reverse functionality, allowing the set of +.B pmie +processes to be cleanly shutdown. +Use of the +.B \-C +option queries the system service runlevel information for +.BR pmie , +and uses that to determine whether to start or stop processes. +.PP +Both +.B pmie_check +and +.B pmie_daily +are controlled by a PCP inference engine control file that specifies the +.B pmie +instances to be managed. The default control file is +.B $PCP_PMIECONTROL_PATH +but an alternate may be specified using the +.B \-c +option. +.PP +The control file should be customized according to the following rules. +.IP 1. +Lines beginning with a ``#'' are comments. +.PD 0 parameters of the +.IP 2. +Lines beginning with a ``$'' are assumed to be +assignments to environment variables in the style of +.BR sh (1), +and all text following the ``$'' will be +.BR eval 'ed +by the script reading the control file, +and the corresponding variable exported into the environment. +This is particularly +useful to set and export variables into the environment of +the administrative script, e.g. +.br +.in +4n +.ft CW +.nf +$ PMCD_CONNECT_TIMEOUT=20 +.fi +.ft R +.in -4n +.br +.BR Warning : +The +.B $PCP_PMIECONTROL_PATH +file must not be writable by any user other than root. +.br +.IP 3. +There should be one line in the control file +for each +.B pmie +instance of the form: + +.in +4n +.ft CW +.nf +\f2host\f1 \f3y\f1|\f3n\f1 \f2logfile\f1 \f2args\f1 +.fi +.ft R +.in -4n + +.IP 4. +Fields within a line of the control file +are separated by one or more spaces or tabs. +.IP 5. +The +.I first +field is the name of the host that is the default source of the +performance metrics for this +.B pmie +instance. +.IP 6. +The +.I second +field indicates whether this +.B pmie +instance needs to be started under the control of +.BR pmsocks (1) +to connect to a +.B pmcd +through a firewall (\c +.B y +or +.BR n ). +.IP 8. +The +.I third +field is the name of the +.B pmie +activity log file. +A useful convention is that +.B pmie +instances monitoring the local host +with hostname +.I myhost +are maintained in the directory +.BI $PCP_LOG_DIR/pmie/ myhost\fR, +while activity logs for the remote host +.I mumble +are maintained in +.BI $PCP_LOG_DIR/pmie/ mumble\fR. +This is consistent with the way +.BR pmlogger (1) +maintains its activity logs and archive files. +.IP 9. +All other fields are interpreted as arguments to be passed to +.BR pmie (1). +Most typically this would be the +.B \-c +option. +.PD +.PP +The following sample control lines specify one +.B pmie +instance monitoring the local host (\c +.IR wobbly ), +and another monitoring performance metrics from the host +.IR splat . +.PP +.nf +.ft CW +wobbly n PCP_LOG_DIR/pmie/wobbly \-c config.default +splat n PCP_LOG_DIR/pmie/splat \-c splat/cpu.conf +.ft 1 +.fi +.PP +Typical +.BR crontab (5) +entries for periodic execution of +.B pmie_daily +and +.B pmie_check +are given in +.BR $PCP_SYSCONF_DIR/pmie/crontab +(unless installed by default in +.IR /etc/cron.d +already) +and shown below. +.PP +.nf +.ft CW +# daily processing of pmie logs +08 0 * * * $PCP_BINADM_DIR/pmie_daily +# every 30 minutes, check pmie instances are running +28,58 * * * * $PCP_BINADM_DIR/pmie_check +.ft 1 +.fi +.PP +The output from the +.BR cron (8) +execution of the scripts may be extended using the +.B \-V +option to the scripts which will enable verbose tracing of their activity. +By default the scripts generate no output unless some error or warning +condition is encountered. +.PP +The +.B \-N +option enables a ``show me'' mode, where the actions are echoed, +but not executed, in the style of ``make \-n''. +Using +.B \-N +in conjunction with +.B \-V +maximizes the diagnostic capabilities for debugging. +.SH FILES +.TP 10 +.B $PCP_PMIECONTROL_PATH +the default PCP inference engine control file +.br +.BR Warning : +this file must not be writable by any user other than root. +.TP +.B $PCP_SYSCONF_DIR/pmie/crontab +sample crontab for automated script execution by $PCP_USER (or root) - +exists only if the platform does not support the +.I /etc/cron.d +mechanism. +.TP +.B $PCP_SYSCONF_DIR/pmie/config.default +default +.B pmlogger +configuration file location for a localhost inference engine, typically +generated automatically by +.BR pmieconf (1). +.TP +.BI $PCP_LOG_DIR/pmie/ hostname +default location for the pmie log file for the host +.I hostname +.TP +.BI $PCP_LOG_DIR/pmie/ hostname /lock +transient lock file to guarantee mutual exclusion during +.B pmie +administration for the host +.I hostname +\- if present, can be safely removed if neither +.B pmie_daily +nor +.B pmie_check +are running +.TP +.B $PCP_LOG_DIR/NOTICES +PCP ``notices'' file used by +.BR pmie (1) +and friends +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.B /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). +.SH SEE ALSO +.BR egrep (1), +.BR PCPintro (1), +.BR pmie (1), +.BR pmieconf (1), +.BR xz (1) +and +.BR cron (8). diff --git a/man/man1/pmieconf.1 b/man/man1/pmieconf.1 new file mode 100644 index 0000000..0b65d0a --- /dev/null +++ b/man/man1/pmieconf.1 @@ -0,0 +1,326 @@ +'\"macro stdmacro +.ie \(.g \{\ +.\" ... groff (hack for khelpcenter, man2html, etc.) +.TH PMIECONF 1 "PCP" "Performance Co-Pilot" +\} +.el \{\ +.if \nX=0 .ds x} PMIECONF 1 "PCP" "Performance Co-Pilot" +.if \nX=1 .ds x} PMIECONF 1 "Performance Co-Pilot" +.if \nX=2 .ds x} PMIECONF 1 "" "\&" +.if \nX=3 .ds x} PMIECONF "" "" "\&" +.TH \*(x} +.rr X +\} +.SH NAME +\f3pmieconf\f1 \- display and set configurable pmie rule variables +.SH SYNOPSIS +\f3pmieconf\f1 +[\f3\-cFv\f1] +[\f3\-f\f1 \f2file\f1] +[\f3\-r\f1 \f2rulepath\f1] +[\f2command\f1 [\f2args...\f1]] +.SH DESCRIPTION +.B pmieconf +is a utility for viewing and configuring variables from generalized +.BR pmie (1) +rules. +The set of generalized rules is read in from +.IR rulepath , +and the output +.I file +produced by +.B pmieconf +is a valid input file for +.BR pmie . +.PP +A brief description of the +.B pmieconf +command line options follows: +.TP 8 +\f3-c\f1 +When run from automated +.B pmie +setup processes, this option is used to add a specific message and +timestamp indicating that this is the case. +It is not appropriate when using the tool interactively. +.TP 8 +\f3\-f\f1 \f2file\f1 +Any rule modifications resulting from +.B pmieconf +manipulation of variable values will be written to \f2file\f1. +The default value of \f2file\f1 is dependent on the user ID \- for the root +user, the file +.I $PCP_VAR_DIR/config/pmieconf/config.pmie +is used, for other users the default is +.IR $HOME/.pcp/pmie/config.pmie . +.TP 8 +\f3\-F\f1 +Forces the +.B pmieconf +output +.I file +to be created (or updated), after which +.B pmieconf +immediately exits. +.TP 8 +\f3\-r\f1 \f2rulepath\f1 +Allows the source of generalized +.B pmie +rules to be changed \- \f2rulepath\f1 is a colon-delimited list of +.BR pmieconf (5) +rule files and/or subdirectories. +The default value for +.I rulepath +is +.IR $PCP_VAR_DIR/config/pmieconf . +Use of this option overrides the +.B PMIECONF_PATH +environment variable which has a similar function. +.TP 8 +\f3\-v\f1 +Verbose mode. Additional information associated with each rule and its +associated variables will be displayed. This is the complete list of +variables which affects any given rule (by default, global variables are +not displayed with the rule). +.PP +The +.B pmieconf +.IR command s +allow information related to the various rules and configurable variables +to be displayed or modified. +If no +.B pmieconf +.IR command s +are presented on the command line, +.B pmieconf +prompts for +.IR command s +interactively. +.PP +The +.B pmieconf +.I command +language is described here: +.TP 8 +.B "help [ { . | all | global | <rule> | <group> } [<variable>] ]" +Without arguments, the +.B help +command displays the syntax for all of the available +.B pmieconf +commands. With one argument, a description of one or more of the generalized +rules is displayed. With two arguments, a description of a specific variable +relating to one or more of the generalized rules is displayed. +.TP 8 +.B "rules [ enabled | disabled ]" +Display the name and short summary for all of the generalized rules found on +.IR rulepath . +Each of the rule names can be used in place of the keyword +.B <rule> +in this command syntax description. +The +.B enabled +and +.B disabled +options can be used to filter the set of rules displayed to just those which +are enabled or disabled respectfully. +.TP 8 +.B "groups" +Display the name of all of the rule groups that were found on +.IR rulepath . +Each of the group names can be used in place of the keyword +.B <group> +in this command syntax description, which applies the command to all rules +within the rule group. +.TP 8 +.B "status" +Display status information relating to the current +.B pmieconf +session, including a list of running +.B pmie +processes which are currently using +.IR file . +.TP 8 +.B "enable { . | all | <rule> | <group> }" +Enables the specified rule or group of rules. An enabled rule is one which +will be included in the +.B pmie +configuration file generated by +.BR pmieconf . +Any enabled "actions" will be appended to the rule's "predicate", in a +manner conforming to the +.B pmie +syntax ("actions" can be viewed using the +.B "list global" +command, described below). +.TP 8 +.B "disable { . | all | <rule> | <group> }" +Disables the specified rule or group of rules. If the rule was previously +enabled, it will be removed from the +.B pmie +configuration file generated by +.BR pmieconf , +and hence no longer evaluated when +.B pmie +is restarted (using +.B pmieconf +does not affect any existing +.B pmie +processes using +.IR file ). +.TP 8 +.B "list { . | all | global | <rule> | <group> } [<variable>]" +Display the values for a specific rule variable; or for all variables of +a rule, a rule group, all rules, or the global variables. +.TP 8 +.B "modify { . | all | global | <rule> | <group> } <variable> <value>" +Enable, disable, or otherwise change the value for one or more rule variables. +This value must be consistent with the type of the variable, which can be +inferred from the format of the printed value - e.g. strings will be enclosed +in double-quotes, percentages have the ``%'' symbol appended, etc. +Note that certain rule variables cannot be modified through +.B pmieconf +\- "predicate" and "help", for example. +.TP 8 +.B "undo { . | all | global | <rule> | <group> } [<variable>]" +Applicable only to a variable whose value has been modified - this +.I command +simply reverts to the default value for the given variable. +.TP 8 +.B "quit" +Save any changes made to +.I file +and then exit +.BR pmieconf . +.TP 8 +.B "abort" +Exit +.B pmieconf +immediately without saving any changes to +.IR file . +.PP +Each of the commands above can be shortened by simply using the first +character of the command name, and also ``?'' for help. +.PP +Use of the +.B all +keyword +causes the command to be applied to all of the rules. +The +.B global +keyword refers to those variables which are applied to every rule. +Such variables can be changed either globally or locally, for example: +.sp +.nf + pmieconf> modify global delta "5 minutes" + pmieconf> modify memory delta "1 minute" +.fi +.sp +causes all rules to now be evaluated once every five minutes, except +for rules in the "memory" group which are to be evaluated once per minute. +.PP +The ``.'' character is special to +.B pmieconf +\- it refers to the last successfully used value of +.BR all , +.BR global , +.B <rule> +or +.BR <group> . +.SH EXAMPLES +Specify that all of the rules in the "memory" group should be evaluated: +.sp +.nf + pmieconf> modify memory enabled yes +.fi +.sp +Change your mind, and revert to using only the "memory" rules which were +enabled by default: +.sp +.nf + pmieconf> undo memory enabled +.fi +.sp +Specify that notification of rules which evaluate to true should be sent to +.BR syslogd (1): +.sp +.nf + pmieconf> modify global syslog_action yes +.fi +.sp +Specify that rules in the "per_cpu" group should use a different holdoff value +to other rules: +.sp +.nf + pmieconf> help global holdoff + rule: global [generic parameters applied to all rules] + var: holdoff + help: Once the predicate is true and the action is executed, + this variable allows suppression of further action + execution until the specified interval has elapsed. + A value of zero enables execution of the action if + the rule predicate is true at the next sample. Default + units are seconds and common units are "second", "sec", + "minute", "min" and "hour". + + pmieconf> modify per_cpu holdoff "1 hour" +.fi +.sp +Lower the threshold associated with a particular variable for a specified +rule: +.sp +.nf + pmieconf> l cpu.syscall predicate + rule: cpu.syscall [High aggregate system call rate] + predicate = + some_host ( + ( kernel.all.syscall $hosts$ ) + > $threshold$ count/sec * hinv.ncpu $hosts$ + ) + + pmieconf> m . threshold 7000 + + pmieconf> l . threshold + rule: cpu.syscall [High aggregate system call rate] + threshold = 7000 +.fi +.sp +.SH ENVIRONMENT +The environment variable +.B PMIECONF_PATH +has a similar function to the +.B \-r +option described above, and if set will be used provided no +.B \-r +option is presented. +.SH FILES +.PD 0 +.TP 10 +.IR $PCP_VAR_DIR/config/pmieconf/ */* +generalized system resource monitoring rules +.TP 10 +.I $PCP_VAR_DIR/config/pmieconf/config.pmie +default super-user settings for system resource monitoring rules +.TP 10 +.I $HOME/.pcp/pmie/config.pmie +default user settings for system resource monitoring rules +.PD +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.I /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). +.SH SEE ALSO +.BR PCPIntro (1), +.BR pmie (1), +.BR pmie_check (1) +and +.BR pmieconf (5). diff --git a/man/man1/pmiestatus.1 b/man/man1/pmiestatus.1 new file mode 100644 index 0000000..4cc08d5 --- /dev/null +++ b/man/man1/pmiestatus.1 @@ -0,0 +1,53 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2010 Max Matveev. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMIESTATUS 1 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmiestatus\f1 \- display information from pmie stats file +.SH SYNOPSIS +\f3pmiestatus\f1 +\f2statsfile\f1 [\f2...\f1] +.SH DESCRIPTION +.B pmiestatus +displays information used to identify a running \f3pmie\f1 process. +It is mostly used by \f3pmie_check\f1 and \f3pmie_daily\f1 when they hunt +for instances of \f3pmie\f1 to check against the control file. +.SH FILES +.PD 0 +.TP 10 +.BI $PCP_TMP_DIR/pmie/ * +pmie stats files +.PD +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.I /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). +.SH SEE ALSO +.BR pmie (1), +.BR pmie_check (1), +.BR pmie_daily (1), +.BR pcp.conf (5), +and +.BR pcp.env (5). diff --git a/man/man1/pminfo.1 b/man/man1/pminfo.1 new file mode 100644 index 0000000..848d93a --- /dev/null +++ b/man/man1/pminfo.1 @@ -0,0 +1,277 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMINFO 1 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pminfo\f1 \- display information about performance metrics +.SH SYNOPSIS +\f3pminfo\f1 +[\f3\-dfFLmMtTvxz\f1] +[\f3\-a\f1 \f2archive\f1] +[\f3\-b\f1 \f2batchsize\f1] +[\f3\-c\f1 \f2dmfile\f1] +[\f3\-h\f1 \f2hostname\f1] +[\f3\-K\f1 \f2spec\f1] +[\f3\-\f1[\f3n\f1|\f3N\f1] \f2pmnsfile\f1] +[\f3\-O\f1 \f2time\f1] +[\f3\-Z\f1 \f2timezone\f1] +[\f2metricname\f1 ...] +.SH DESCRIPTION +.B pminfo +displays various types of information about performance metrics +available through the facilities of the Performance Co-Pilot (PCP). +.PP +Normally +.B pminfo +operates on the distributed Performance Metrics Name Space (PMNS), however +if the +.B \-n +option is specified an alternative local PMNS is loaded +from the file +.IR pmnsfile. +The +.B \-N +option supports the same function as +.BR \-n , +except for the handling of +duplicate Performance Metric Identifiers (PMIDs) in +.I pmnsfile +\- duplicates are allowed with +.B \-N +they are not allowed with +.BR \-n . +.PP +The metrics of interest are named in the +.I metricname +arguments. +If +.I metricname +is a non-leaf node in the PMNS, then +.B pminfo +will recursively descend the PMNS and report on all leaf nodes. +If no +.I metricname +argument is given, the root of the PMNS is used. +.PP +Unless directed to another host by the +.B \-h +option, by default +.B pminfo +will contact the Performance Metrics Collector Daemon +(PMCD) on the local host. +The connection to a PMCD is only required if +.B pminfo +requires distributed PMNS information, and/or meta-data +describing metrics, and/or metric values, and/or help text. +.PP +The +.B \-a +option causes +.B pminfo +to use the specified archive rather than connecting to a PMCD. The +.B \-a , \-h +and +.B \-L +options are mutually exclusive. +.PP +The +.B \-L +option causes +.B pminfo +to use a local context to collect metrics from PMDAs on the local host +without PMCD. Only some metrics are available in this mode. +The +.BR \-a , \-h +and +.B \-L +options are mutually exclusive. +.PP +The +.B \-b +option may be used to define the maximum size of the group of metrics to +be fetched in a single request for the +.B \-f +and +.B \-v +options. The default value for +.I batchsize +is 20. +.PP +Other options control the specific information to be reported. +.TP 5 +.B \-c +The +.I dmfile +argument specifies a file that contains derived metric definitions +in the format described for +.BR pmLoadDerivedConfig (3). +The +.B \-c +option provides a way to load derived metric definitions +that is an alternative to the more generic use of the +.B PCP_DERIVED_CONFIG +environment variable as described in +.BR PCPIntro (1). +Using the +.B \-c +option and the +.B PCP_DERIVED_CONFIG +environment variable to specify the +.B same +configuration is a bad idea, so choose one or the other method. +.TP +.B \-d +Metric descriptions detailing the PMID, data type, data semantics, units, +scale and associated instance domain. +.TP +.B \-f +Fetch and print values for all instances. +When fetching from an archive, only +those instances present in the first archive record for a metric will be +displayed; see also the +.B \-O +option, else use +.BR pmdumplog (1) +which may be a better tool for examining archives. +.TP +.B \-F +Same as +.B \-f +but try harder to fetch instances for metrics which have non-enumerable +instance domains (e.g. metrics in the ``proc'' subtree of the default +PMNS). +.TP +.B \-K +When using the +.B \-L +option to fetch metrics from a local context, the +.B \-K +option may be used to control the DSO PMDAs that should be +made accessible. The +.I spec +argument conforms to the syntax described in +.BR __pmSpecLocalPMDA (3). +More than one +.B \-K +option may be used. +.TP +.B \-m +Print the PMID in terse mode. +.TP +.B \-M +Print the PMID in verbose mode. +.TP +.B \-O +When used in conjunction with an archive source of metrics and +the options +.B \-f +or +.BR \-F , +the +.I time +argument defines a time origin at which the metrics should be +fetched from the archive. +Refer to +.BR PCPIntro (1) +for a complete description of this option, and the syntax for the +.I time +argument. +.RS +.PP +When the ``ctime'' format is used for the +.I time +argument in a +.B \-O +option, the timezone becomes an issue. +The default is to use the +local timezone on the +system where +.B pminfo +is run. +The +.B \-Z +option changes the timezone to +.I timezone +in the format of the environment variable +.B TZ +as described in +.BR environ (5). +The +.B \-z +option changes the timezone to the local timezone at the +host that is the source of the performance metrics, as identified via +the +.B \-a +option. +.RE +.TP +.B \-t +Print the ``one line'' help summary, if available. +.TP +.B \-T +Print the help text, if available. +.TP +.B \-v +Verify mode in which descriptions and values are retrieved, but only +error conditions are reported. This option silently disables any +output from the options +.BR \-f , +.BR \-M , +.BR \-m , +.B \-t +and +.BR \-T . +.TP +.B \-x +Like the +.B \-f +option, but with the additional functionality that if a value is +processed that is of type PM_TYPE_EVENT, then the event records +will be unpacked and the details of each event record reported. +.SH FILES +.PD 0 +.TP 10 +.BI $PCP_VAR_DIR/pmns/ * +default local PMNS specification files +.PD +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.I /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). +.SH SEE ALSO +.BR PCPIntro (1), +.BR pmcd (1), +.BR pmchart (1), +.BR pmdumplog (1), +.BR pmdumptext (1), +.BR pmprobe (1), +.BR pmval (1), +.BR PMAPI (3), +.BR pmLoadDerivedConfig (3), +.BR __pmSpecLocalPMDA (3), +.BR pcp.conf (5), +.BR pcp.env (5) +and +.BR pmns (5). diff --git a/man/man1/pmiostat.1 b/man/man1/pmiostat.1 new file mode 100644 index 0000000..d2827a7 --- /dev/null +++ b/man/man1/pmiostat.1 @@ -0,0 +1,230 @@ +'\"! tbl | mmdoc +'\"macro stdmacro +.\" +.\" Copyright (c) 2014 Red Hat Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMIOSTAT 1 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmiostat\f1 \- performance metrics value dumper +.\" literals use .B or \f3 +.\" arguments use .I or \f2 +.SH SYNOPSIS +\f3pmiostat\f1 +[\f3\-A\f1 \f2align\f1 \f3--align=\f2TIME\f1] +[\f3\-a\f1 \f2archive\f1 \f3--archive=\f2FILE\f1] +[\f3\-h\f1 \f2host\f1 \f3--host=\f2HOST\f1] +[\f3\-O\f1 \f2offset\f1 \f3--origin=\f2TIME\f1] +[\f3\-S\f1 \f2starttime\f1 \f3--start=\f2TIME\f1] +[\f3\-s\f1 \f2samples\f1 \f3--samples=\f2N\f1] +[\f3\-T\f1 \f2endtime\f1 \f3--finish=\f2TIME\f1] +[\f3\-t\f1 \f2interval\f1 \f3--interval=\f2DELTA\f1] +[\f3\-Z\f1 \f2timezone\f1 \f3--timezone=\f2TZ\f1] +[\f3\-z\f1 \f3--hostzone\f1] +[\f3\-?\f1 \f3--help\f1] +[\f3\-x\f1 [dm][,t][,h]\f1] +.SH DESCRIPTION +.de EX +.in +0.5i +.ie t .ft CB +.el .ft B +.ie t .sp .5v +.el .sp +.ta \\w' 'u*8 +.nf +.. +.de EE +.fi +.ie t .sp .5v +.el .sp +.ft R +.in +.. +.B pmiostat +reports I/O statistics for scsi devices (by default) or device-mapper devices (if the \f3-x dm\f1 option is specified). +By default +.B pmiostat +reports live data for the local host but can also report for a remote host (\f3-h\fP) or from a previously captured PCP archive (\f3-a\fP). +.PP +The +.BR \-S , +.BR \-T , +.BR \-O +and +.B \-A +options may be used to define a time window to restrict the +samples retrieved, set an initial origin within the time window, +or specify a ``natural'' alignment of the sample times; refer to +.BR PCPIntro (1) +for a complete description of these options. +.PP +The other options which control the source, timing and layout of the information +reported by +.B pmiostat +are as follows: +.TP 5 +.B \-a +Performance metric values are retrieved from the Performance Co-Pilot (PCP) +archive log file identified by the base name +.IR archive . +.TP +.B \-h +Current performance metric values are retrieved from the nominated +.I host +machine. +.TP +.B \-s +The argument +.I samples +defines the number of samples to be retrieved and reported. +If +.I samples +is 0 or +.B \-s +is not specified, +.B pmiostat +will sample and report continuously (in real time mode) or until the end +of the PCP archive (in archive mode). +.TP +.B \-t +The default update \f2interval\f1 may be set to something other than the +default 1 second. +The +.I interval +argument follows the syntax described in +.BR PCPIntro (1), +and in the simplest form may be an unsigned integer (the implied +units in this case are seconds). +The \f3-t\fP option is particularly useful when replaying large archives (\f3-a\fP option) that span several hours or even days. +In this case specifying a large +.I interval +(e.g. 1h for 1 hour) +will reduce the volume of data reported and the i/o statistics will be averaged (interpolated) over +the reporting interval. +.TP +.B \-Z +By default, +.B pmiostat +reports the time of day according to the local timezone on the +system where +.B pmiostat +is run. +The +.B \-Z +option changes the timezone to +.I timezone +in the format of the environment variable +.B TZ +as described in +.BR environ (5). +.TP +.B \-z +Change the reporting timezone to the local timezone at the host that is +the source of the performance metrics, as identified via either the +.B \-h +or +.B \-a +options. +.TP +.B \-x +Specifies a comma separated list of one or more extended reporting options as follows: +.br +\f3dm\fP - report statistics for device-mapper logical devices instead of scsi devices, +.br +\f3t\fP - prefix every line in the report with a timestamp in \f2ctime\fP(3) format, +.br +\f3H\fP - omit the heading, which is otherwise reported every 24 samples. +.SH REPORT +The columns in the +.B pmiostat +report have the following interpretation : +.TP +.B Timestamp +When the \f3-x t\fP option is specified, this column is the timestamp in \f3ctime\fP(3) format. +.TP +.B Device +Specifies the scsi device name, or if \f3-x dm\fP is specified, the device-mapper logical device name. +.TP +.B rrqm/s +The number of read requests expressed as a rate per-second that were merged +during the reporting interval by the I/O scheduler. +.TP +.B wrqm/s +The number of write requests expressed as a rate per-second that were merged +during the reporting interval by the I/O scheduler. +.TP +.B r/s +The number of read requests completed by the device (after merges), expressed as a rate per second during the reporting interval. +.TP +.B w/s +The number of write requests completed by the device (after merges), expressed as a rate per second during the reporting interval. +.TP +.B rkB/s +The average volume of data read from the device expressed as KBytes/second during the reporting interval. +.TP +.B wkB/s +The average volume of data written to the device expressed as KBytes/second during the reporting interval. +.TP +.B avgrq-sz +The average I/O request size for both reads and writes to the device expressed as Kbytes during the reporting interval. +.TP +.B avgqu-sz +The average queue length of read and write requests to the device during the reporting interval. +.TP +.B await +The average time in milliseconds that read and write requests were queued (and serviced) to the device during the reporting interval. +.TP +.B r_await +The average time in milliseconds that read requests were queued (and serviced) to the device during the reporting interval. +.TP +.B w_await +The average time in milliseconds that write requests were queued (and serviced) to the device during the reporting interval. +.TP +.B %util +The percentage of time during the reporting interval that the device was busy processing requests. +A value of 100% indicates device saturation. +.SH FILES +.PD 0 +.TP 10 +.BI $PCP_VAR_DIR/pmns/ * +default PMNS specification files +.PD +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.I /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). +.SH SEE ALSO +.BR PCPIntro (1), +.BR pmcd (1), +.BR pmchart (1), +.BR pmdumplog (1), +.BR pminfo (1), +.BR pmlogger (1), +.BR pmtime (1), +.BR PMAPI (3), +.BR __pmSpecLocalPMDA (3), +.BR pcp.conf (5) +and +.BR pcp.env (5). +.SH DIAGNOSTICS +All are generated on standard error and are intended to be self-explanatory. diff --git a/man/man1/pmlc.1 b/man/man1/pmlc.1 new file mode 100644 index 0000000..78be5bf --- /dev/null +++ b/man/man1/pmlc.1 @@ -0,0 +1,477 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMLC 1 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmlc\f1 \- configure active Performance Co-Pilot pmlogger(s) interactively +.\" literals use .B or \f3 +.\" arguments use .I or \f2 +.SH SYNOPSIS +\f3pmlc\f1 +[\f3\-e\f1] +[\f3\-h\f1 \f2host\f1] +[\f3\-i\f1] +[\f3\-n\f1 \f2pmnsfile\f1] +[\f3\-P\f1] +[\f3\-p\f1 \f2port\f1] +[\f3\-Z\f1 \f2timezone\f1] +[\f3\-z\f1] +[\f3pid\f1] +.SH DESCRIPTION +.B pmlc +may be used to change those metrics and instances which a +.BR pmlogger (1) +writes to a Performance Co-Pilot archive (see +.BR PCPIntro (1)), +the frequency with which the metrics are collected and whether the +logging is mandatory, advisory, on or off. It also reports the +current logging status of metrics and instances. +.B pmlc +may be used to control pmlogger instances on remote hosts as well as those +on the local host. +.PP +Normally +.B pmlc +operates on the distributed Performance Metrics Name Space (PMNS), however +if the +.B \-n +option is specified an alternative local PMNS is loaded from the file +.IR pmnsfile . +.PP +If the +.B \-P +option is specified, +.B pmlc +will attempt to start with a connection to the primary pmlogger on the +local host. If the +.B \-p +option is specified, then +.B pmlc +will attempt to start with a connection to the pmlogger on this TCP/IP +.IR port . +Alternatively, if +.I pid +is specified, a connection to the pmlogger instance with that process +id will be attempted on startup. The +.B \-h +option may only be used if +.BR \-P, +.B \-p +.I port +or a +.I pid +is also specified. In that case +.B pmlc +will initially connect to the specified (remote) pmlogger instance on +.I host +rather than the local host. If the connection to the specified pmlogger +instance cannot be established, +.B pmlc +will start with no connection. These options typically allow the same file of +.B pmlc +commands to be directed to multiple pmlogger instances by varying the +command line arguments. Note that +.BR -P , +.B \-p +.IR port , +.IR pid +and +.B \-h +are used only when making an initial connection to a pmlogger +instance. They are not used as defaults if subsequent connections are made +interactively (see the +.B connect +command below). +.PP +By default, +.B pmlc +reports the time of day according to the local timezone on the +system where +.B pmlc +is run. The +.B \-Z +option changes the timezone to +.IR timezone +in the format of the environment variable +.B TZ +as described in +.BR environ (5). +The +.B \-z +option changes the timezone to the timezone of the pmlogger +instance from which information is being obtained. Only one of +.B \-z +or +.B \-Z +may be specified. +.PP +If standard input is from a tty, +.B pmlc +is interactive, with prompts. +The +.B \-i +flag may be used to force interactive behavior, and is typically +used in conjunction with +.B \-e +to echo all command input on standard output. +.PP +The following commands may be used: +.PP +.TP 4 +\f3show\f1 [ \f3loggers\f1 ] [ \f3@\f2host\f1 ] +Displays the process identities of all pmlogger instances running +on the local host (or +.IR host , +if specified). The primary pmlogger pid is parenthesized because +it can be referred to as "primary" as well as by its pid. +.TP 4 +\f3connect\f1 \f2pid\f1 [ \f3@\f2host\f1 ] +.br +.in -4 +\f3connect\f1 \f3primary\f1 [ \f3@\f2host\f1 ] +.in +Connects +.B pmlc +to the specified pmlogger process. Any existing connection to +a pmlogger instance is closed first. Each pmlogger instance will +accept at most one connection at a time, so if the connection is +successfully established, your +.B pmlc +will be the only one controlling the pmlogger instance it is connected to. +.TP 4 +\f3new volume\f1 +This command works only while a connection to a pmlogger +instance is established. It tells the pmlogger to close the current +volume of the log and open a new volume. Closed volumes may be archived, +e.g. as part of a regular log management procedure to control the size of +the physical log files. +.TP 4 +\f3status\f1 +This command works only while a connection to a pmlogger instance is +established. It prints information about the state of the pmlogger +instance and its associated log. +.TP 4 +\f3timezone\f1 \f3local\f1 | \f3logger\f1 | \f3"\f2timezone\f3"\f1 +This command sets the time zone used when times are printed. +.B local +means use the time zone of the machine that +.B pmlc +is running on. +.B logger +means use the time zone of the machine where the pmlogger +instance is +running. Alternatively an explicit +.I timezone +enclosed in quotes may be supplied (refer to +.B TZ +in +.BR environ (5) +for details). The default time zone is +.B local +unless one of the +.B \-z +or +.B \-Z +options has been supplied on the command line. +.TP 4 +\f3flush\f1 +This command works only while a connection to a pmlogger instance is +established, and requests the pmlogger instance +to flush to disk all buffers associated with the current archive. +For old-timers, \f3sync\f1 is a synonym for \f3flush\f1. +In current versions of +.BR pmlogger (1) +all writes are unbuffered and aligned with the logical records in the external +files, so this command achieves nothing, but is retained for backwards +compatibility. +.TP 4 +\f3help\f1 +Displays a summary of the available commands. +.sp 0.5v +\f3h\f1 and \f3?\f1 are synonyms for \f3help\f1. +.TP 4 +\f3quit\f1 +Exits from +.BR pmlc . +.PP +The remaining commands query and change the logging state of metrics and +instances. They will work only if +.B pmlc +has a connection to a pmlogger instance. Metrics may be specified as fully +qualified names (e.g. hinv.ncpu) or subtrees of the PMNS (e.g. hinv) which +are expanded to include all metrics in the subtree (e.g. hinv.ncpu, +hinv.cpuclock, etc.). Lists of metrics may be specified by enclosing them +in braces with spaces or a comma between metrics (e.g. {hinv.ncpu +hinv.ndisk}). Subtrees of metrics may be included in such lists. +.PP +Each individual metric specification may be further qualified with a space +or comma separated list of instances in square brackets +(e.g. kernel.all.load["1 minute", "5 minute"]). External instance +names or numeric internal instance identifiers or both may be used in the +same list (e.g. sample.colour.[red,1,"blue"]). +If an instance qualification is applied to a subtree of the PMNS all of the +metrics in the subtree must have the same instance domain. Instance +qualifications may not be applied to entire lists of metrics but may appear +inside such lists. +.PP +If no instances are specified for a metric, all instances are used. All +instances means all instances available at the time the pmlogger instance in +question fetches the metrics for logging. If an instance domain changes over +time this is not always the same as the set of instances displayed by +.BR pmlc , +which can only display the currently available instances. To prevent +unintentional errors, only the instances that are currently available to +.B pmlc +may appear in instance specifications. +.TP 4 +\f3query\f2 metriclist\f1 +The current logging state of each metric (and instances, where applicable) in +.I metriclist +is displayed. This includes the logging state (e.g. on, maybe, off) and the +logging interval for each metric (and instance) requested. The following +abbreviations pertaining to metrics (and instances) may appear in the output: +.BR adv , +advisory; +.BR mand , +mandatory; +.BR nl , +not in the log; +.BR na , +in the log but not currently available from its Performance Metrics Domain +Agent (PMDA). Where appropriate, an instance name will appear last on a line +preceded by its numeric internal instance identifier. +.TP 4 +[ \f3log\f1 ] \f3mandatory on\f2 interval\f1 \f2metriclist\f1 +This form of the +.B log +command turns on logging for the metrics (and any instances) in +.IR metriclist. +.I interval +specifies how often the specified metrics/instances should be logged. +.B once +indicates that the metrics/instances should appear at most once in the log. +More often one would use the optional keyword +.B every +followed by a positive number and one of +.B millisecond +(or +.BR msec ), +.B second +(or +.BR sec ), +.B minute +(or +.BR min ), +.B hour +or their plurals. +.sp 0.5v +Note that the keyword +.B default +which may be used for the default +.I interval +in a +.BR pmlogger (1) +configuration file cannot be used in +.BR pmlc . +.sp 0.5v +Internal limitations require the +.I interval +to be less than (approximately) 74 hours. An +.I interval +value of zero is a synonym for +.BR once . +.TP 4 +[ \f3log\f1 ] \f3mandatory off\f1 \f2metriclist\f1 +This tells the pmlogger instance not to log any of the metrics/instances in +.IR metriclist . +.TP 4 +[ \f3log\f1 ] \f3mandatory maybe\f1 \f2metriclist\f1 +This tells the pmlogger instance to honor any subsequent advisory logging +requests for the metrics/instances in +.IR metriclist . +If the current logging state of the metrics/instances is mandatory (either on +or off) the new state will be set to maybe (effectively advisory off). If the +current state of the metrics/instances is already advisory (either on or off) +the state(s) for the metrics/instances will remain as they are. +.TP 4 +[ \f3log\f1 ] \f3advisory on\f2 interval\f1 \f2metriclist\f1 +.br +.in -4 +[ \f3log\f1 ] \f3advisory off\f1 \f2metriclist\f1 +.in +Advisory logging is only applicable if the last logging state specified for a +metric/instance was "mandatory maybe" (which permits subsequent advisory +logging control) or if the logging state is already advisory. These two +statements turn advisory logging on or off (respectively) for the specified +metrics/instances. +.sp 0.5v +The interpretation for +.I interval +is as above for the +.B mandatory +case. +.PP +There is no continuation character required for commands that span lines. +.PP +The word +.B at +may be used interchangeably with +.BR @ . +.PP +A request to log all instances of a metric will supersede any prior request to +log either all or specific instances of a metric (if the request specifies a +permissible transition in the logging state). A request to log specific +instances of a metric when all instances of a metric are already being logged +is refused by +.BR pmlogger . +.SH "ACCESS CONTROL" +.B pmlc +may have restricted access to and control over +.BR pmlogger (1) +processes. +.PP +If a +.BR pmlogger (1) +is unable to export its control information to the local +.BR pmcd (1), +then that +.BR pmlogger (1) +cannot cannot be connected to nor controlled by +.BR pmlc . +In practice, this means the +.BR pmlogger (1) +process has to be owned by the user ``pcp'' and/or the group ``pcp''. +If +.BR pmlogger (1) +is running on the host ``foo'' then +use ``pminfo -f -h foo pmcd.pmlogger'' to verify that the +.BR pmlogger (1) +of interest is known to +.BR pmcd (1), +alternatively +.BR pmlogger (1) +instances that are not reported from the +.B pmlc +.B "show loggers @foo" +command are not known to +.BR pmcd (1) +on the host ``foo''. +.PP +If +.BR pmlogger (1) +is launched with a configuration file that contains an +.B [access] +section, then +.B pmlc +will be unable to connect to that +.BR pmlogger (1) +unless the access controls allow +.B some +access from the host where +.B pmlc +is being run. +Minimally this requires the +.B enquire +access to be permitted in the +.BR pmlogger (1) +access control section. +.PP +If +.B pmlc +is able to connect to the +.BR pmlogger (1) +of interest, then the following table summarizes the permissions needed +to perform different +.B pmlc +commands: +.TS +box,center; +c | c +lf(B) | l. +\fBpmlc\fP command Required \fBpmlogger\fP access += +show loggers Any +connect Any of \fBenquire\fP, \fBadvisory\fP or \fBmandatory\fP +status Any of \fBenquire\fP, \fBadvisory\fP or \fBmandatory\fP +query \fR...\fP Any of \fBenquire\fP, \fBadvisory\fP or \fBmandatory\fP +log advisory \fR...\fP \fBadvisory\fP +log mandatory \fR...\fP \fBmandatory\fP +new volume \fBmandatory\fP +.TE +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.I /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). +.SH SEE ALSO +.BR PCPIntro (1), +.BR pmcd (1), +.BR pmdumplog (1), +.BR pmlogger (1), +.BR pcp.conf (5), +.BR pcp.env (5) +and +.BR environ (5). +.SH DIAGNOSTICS +Most error or warning messages are self-explanatory. A message of the form +.br +.in +05.v +Warning: unable to change logging state for... +.in +followed by a list of metrics (and possibly instances) indicates that +.B pmlogger +refused the request for the metrics (and instances) that appear. Any metrics +(and instances) that were specified but do not appear in the message have had +their logging state updated successfully (no news is good news). Usually this +warning results from requesting advisory logging when a mandatory control is +already in place, or requesting logging for specific instances when all +instances are already being logged. +.SH CAVEAT +If all instances of a metric are being logged and a request is made to log +specific instances of the metric with the same state and frequency, the request +may appear to succeed, even though +.B pmlogger +has refused the request. This is not normally a problem, as the required +information will still be placed into the log by +.BR pmlogger . +.PP +However in the case where the metric is to be logged once, the outcome is not +what might be expected. When +.B pmlogger +receives a request to log a metric once, it places the current value(s) of the +metric into the log as soon as it can, regardless of whether the metric is +already in the log. This may be used to force values into the log. When a +request to log specific instances of a metric arrives and is refused because +all instances of the metric are already being logged, +.B pmlogger +does not place values for the instances requested into the log. It returns +the current logging state for each instance requested to +.BR pmlc . +The requested and returned states are identical, so +.B pmlc +doesn't raise an error as it should. +.PP +To ensure that only certain instances of a metric are being logged, one should +always turn off logging for all instances of the metric prior to turning on +logging for the specific instances required. diff --git a/man/man1/pmlock.1 b/man/man1/pmlock.1 new file mode 100644 index 0000000..4272d29 --- /dev/null +++ b/man/man1/pmlock.1 @@ -0,0 +1,41 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMLOCK 1 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmlock\f1 \- simple file-based mutex +.\" literals use .B or \f3 +.\" arguments use .I or \f2 +.SH SYNOPSIS +.B $PCP_BINADM_DIR/pmlock +[ +.B \-v +] +.I file +.SH DESCRIPTION +.B pmlock +attempts to acquire an exclusive lock by creating +.I file +with a mode of 0. +.PP +The exit status is 0 for success, 1 for failure. +.PP +To release the lock, unlink +.IR file . +.PP +In the event of a failure, the +.B \-v +option produces an explanatory message on +.IR stdout . diff --git a/man/man1/pmlogcheck.1 b/man/man1/pmlogcheck.1 new file mode 100644 index 0000000..8c64159 --- /dev/null +++ b/man/man1/pmlogcheck.1 @@ -0,0 +1,138 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMLOGCHECK 1 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmlogcheck\f1 \- checks for invalid data in a PCP archive +.SH SYNOPSIS +\f3pmlogcheck\f1 +[\f3\-lz\f1] +[\f3\-n\f1 \f2pmnsfile\f1] +[\f3\-S\f1 \f2start\f1] +[\f3\-T\f1 \f2finish\f1] +[\f3\-Z\f1 \f2timezone\f1] +\f2archive\f1 +.SH DESCRIPTION +.B pmlogcheck +prints information about the nature of any invalid data which it detects +in a PCP archive. Of particular interest are wrapped values for metrics +which are expected to have monotonically increasing values. +The archive has the base name +.I archive +and must have been previously created using +.BR pmlogger (1). +.PP +Normally +.B pmlogcheck +operates on the default Performance Metrics Namespace (\c +.BR pmns (5)), +however if the +.B \-n +option is specified an alternative namespace is loaded +from the file +.IR pmnsfile . +.PP +The command line options +.B \-S +and +.B \-T +can be used to specify a time window over which metrics should be summarized. +These options are common to many Performance Co-Pilot tools and are fully +described in +.BR PCPIntro (1). +.PP +The +.B \-l +option prints the archive label, showing the log format version, +the time and date for the start and (current) end of the archive, and +the host from which the performance metrics values were collected. +.PP +By default, +.B pmlogcheck +reports the time of day according to the local timezone on the +system where +.B pmlogcheck +is run. +The +.B \-Z +option changes the timezone to +.I timezone +in the format of the environment variable +.B TZ +as described in +.BR environ (5). +The +.B \-z +option changes the timezone to the local timezone at the +host that is the source of the performance metrics, as specified in +the label record of the archive log. +.SH OUTPUT FORMAT +For each metric having ``counter'' semantics (i.e. the metric is expected to +increase monotonically) which has been detected as having wrapped at some +point in the archive, +.B pmlogcheck +produces output describing the metric name (with instance identifiers where +appropriate), the internal storage type for the metric, the value of the +metric before the counter wrap (with its associated timestamp), and the value of +the metric after the wrap (also with a timestamp). +.PP +.B pmlogcheck +produces two different timestamp formats, depending on the interval over +which it is run. For an interval greater than 24 hours, the date is displayed +in addition to the time at which the counter wrap occurred. +If the extent of the data being checked is less than 24 hours, a more +precise format is used (time is displayed with millisecond precision, but +without the date). +.PP +.SH FILES +.PD 0 +.TP 10 +.BI $PCP_VAR_DIR/pmns/ * +default PMNS specification files +.TP +.BI $PCP_LOG_DIR/pmlogger/ hostname +default directory for PCP archives containing performance data collected +from the host +.IR hostname . +.PD +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.I /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). +.SH SEE ALSO +.BR PCPIntro (1), +.BR pmdumplog (1), +.BR pmlogextract (1), +.BR pmlogger (1), +.BR pmlogextract (1), +.BR pmlogsummary (1), +.BR pmval (1), +.BR pcp.conf (5), +.BR pcp.env (5) +and +.BR pmns (5). +.SH DIAGNOSTICS +All are generated on standard error and are intended to be self- +explanatory. diff --git a/man/man1/pmlogconf.1 b/man/man1/pmlogconf.1 new file mode 100644 index 0000000..219f358 --- /dev/null +++ b/man/man1/pmlogconf.1 @@ -0,0 +1,368 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2013 Red Hat. +.\" Copyright (c) 2000 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMLOGCONF 1 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmlogconf\f1 \- create/edit a pmlogger configuration file +.SH SYNOPSIS +\f3$PCP_BINADM_DIR/pmlogconf\f1 +[\f3\-cqrv\f1] +[\f3\-d\f2 groupsdir\f1] +[\f3\-h\f2 hostname\f1] +\f2configfile\f1 +.SH DESCRIPTION +.B pmlogconf +may be used to create and modify a generic configuration file for +the PCP archive logger, +.BR pmlogger (1). +.PP +If +.I configfile +does not exist, +.B pmlogconf +will create a generic configuration file with a +default set of enabled metrics and logging intervals. +.PP +Once created, +.I configfile +may be used with the +.B \-c +option to +.BR pmlogger (1) +to select performance metrics and specify +logging intervals for a PCP archive. +.PP +If +.I configfile +does exist, +.B pmlogconf +will prompt for input from the user to enable or disable groups +of related performance metrics and to control the logging interval +for each enabled group. +.PP +Group selection requires a simple +.B y +(yes) +or +.B n +(no) response to the prompt +.BR "Log this group?" . +.PP +Other responses at this point may be used to select +additional control functions as follows: +.IP \fBm\fP 10n +Report the names of the metrics in the current group. +.IP \fBq\fP 10n +Finish with group selection (quit) and make no further changes to +this group or any subsequent group. +.IP \fB/\fIpattern\fP 10n +Make no change to this group but search for a group containing +.I pattern +in the description of the group or the names +of the associated metrics. +.PP +A logging interval is specified by responding to the +.B "Logging interval?" +prompt with the keywords +.B once +or +.B default +or a valid +.BR pmlogger (1) +interval specification of the form ``\c +.B every +.IR "N timeunits" '' +or simply ``\c +.I "N timeunits" '' +(the +.B every +is optional) where +.I N +is an unsigned integer and +.I timeunits +is one of the keywords +.BR msec , +.BR millisecond , +.BR sec , +.BR second , +.BR min , +.BR minute , +.BR hour +or the plural form of one of the keywords. +.PP +When run from automated logging setup processes, the +.B \-c +option is used to add a message and timestamp indicating this fact. +This option is not appropriate for interactive use of the tool. +.PP +The +.B \-q +option suppresses the logging interval dialog and preserves the +current interval from +.IR configfile . +.PP +More verbose output may be enabled with the +.B \-v +option. +.SH "SETUP GROUP FILES" +When an initial +.I configfile +is created, the default specifications come from a set of group +files below the +.I groupsdir +specified with the +.B \-d +option (the default +.I groupsdir +is +.B $PCP_VAR_DIR/config/pmlogconf +which is most commonly correct, so the +.B \-d +option is rarely used in practice). +.PP +The directory structure below +.I groupsdir +is arbitrary as all regular files will be found by recursive descent and considered, so add-on products +and PMDA developers can easily extend the available defaults to +.B pmlogconf +by adding new directories and/or group files below +.IR groupsdir . +.PP +These group files are processed in the following ways: +.IP \(bu 3n +When a new +.I configfile +is created, all group files are processed. +.IP \(bu 3n +Whenever +.B pmlogconf +is run with an existing +.IR configfile , +.I groupsdir +is traversed to see if any new groups have been defined and should be +considered for inclusion in +.IR configfile . +.IP \(bu 3n +When +.B pmlogconf +processes a group in +.I configfile +that is enabled, the list of metrics associated with the group is +taken from the group file (and replaces any previous list of metrics +associated with this group in +.IR configfile ). +.IP \(bu 3n +When the +.B \-r +(reprobe) command line option is specified, every group (not just newly +discovered ones) is reprocessed to see +if it should be considered for inclusion in +.IR configfile . +.PP +Each group file is structured as follows: +.IP \(bu 3n +The first line must contain +.B #pmlogconf-setup 2.0 +.IP \(bu 3n +Other lines beginning with +.B # +are treated as comments. +.IP \(bu 3n +Blank lines are ignored. +.IP \(bu 3n +One or more lines starting with the keyword +.B ident +are used to provide the human-readable description of the group. +.IP \(bu 3n +Non-blank lines beginning with white space define metrics to be associated +with this group, one per line. Each metric specification follows the rules +for a +.BR pmlogger (1) +configuration, namely either the name of a non-leaf node in the PMNS +(implying all descendent names in the PMNS), or the name of a leaf +node in the PMNS optionally followed by one or more instance names +enclosed by ``['' and ``]''. +.IP \(bu 3n +A control line starting with one of the keywords +.B probe +or +.B force +must be present. +.IP \(bu 3n +An optional logging interval control line begins with the +keyword +.B delta +followed by one of the +.BR pmlogger (1) +interval specification described above. +.IP \(bu 3n +.B probe +control lines have the format: +.RS 3n +.br +.ce +\fBprobe\fR \fImetric\fR [\fIcondition\fR [\fIstate_rule\fR] ] +.br +where +.I metric +is the name of a PCP metric (must be a leaf node in the PMNS and +no instance specification is allowed) and the optional +.I condition +is the keyword +.B exists +(true if +.I metric +exists, i.e. is defined in the PMNS) or the keyword +.B values +(true if +.I metric +exists in the PMNS and has one or more current values) +or an expression of the form +.br +.ce +\fIop\fR \fIval\fR +where +.I op +is one of the +.BR awk (1) +operators (\fB==\fR, \fB!=\fR, \fB>\fR, \fB>=\fR, \fB<\fR, \fB<=\fR, +\fB~\fR (regular expression match) or +\fB!~\fR (negated regular expression match)) +and +.I val +is a value (arbitrary sequence of characters, excluding a space) +and the +.I condition +is true if there is some instance of +.I metric +that makes the expression true. +.PP +If the +.I condition +is missing, the default is +.BR exists . +.PP +When an explicit +.I condition +is provided, there may also be an optional +.I state_rule +of the form +.br +.ce +\fB?\fR \fItrue_state\fR \fB:\fR \fIfalse_state\fR +where +.I true_state +(applies if +.I condition +is true) and +.I false_state +(applies if +.I condition +is false) are both taken from the keywords +.B include +(include and enable the group and the associated metrics in +.IR configfile ), +.B available +(include and disable the group in +.I configfile +\- a user action of +.B y +as described above is needed to enable the group and +add the associated metrics into +.IR configfile ) +or +.B exclude +(the group is not considered for inclusion in +.IR configfile ). +.PP +The default +.I state_rule +is +.br +.ce +.ft B +? available : exclude +.ft R +.RE +.IP \(bu 3n +.B force +control lines begin with the keyword +.B force +followed by one of the states defined above, so +one of the actions +.BR include , +.B exclude +or +.B available +is applied unconditionally to the group. +.PP +Probing is only done when a new group is being added to +.I configfile +or when the +.B \-r +command line option is specified. The evaluation of the probing +conditions is done by contacting +.BR pmcd (1) +on +.I hostname +(defaults to local:). +.SH EXAMPLE +The following group file demonstrates all of the supported +syntactic elements. +.PP +.ft CW +.nf +#pmlogconf-setup 2.0 +ident Example group file +ident ... more description +delta 1 minute +probe sample.secret.foo.one values ? include : exclude + sample.secret.foo.one + sample.secret.foo.bar # non-leaf in the PMNS + sample.colour [ red green ] +.fi +.ft +.SH MIGRATION +The current version of +.B pmlogconf +(2.0) +supports a slightly different format for +.I configfile +compared to earlier versions. If an old version +.I configfile +is presented to +.B pmlogconf +it will be converted to the new format. +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.I /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). +.SH SEE ALSO +.BR pmcd (1), +.BR pmlogger (1), +.BR pcp.conf (5) +and +.BR pcp.env (5). diff --git a/man/man1/pmlogextract.1 b/man/man1/pmlogextract.1 new file mode 100644 index 0000000..bfbc553 --- /dev/null +++ b/man/man1/pmlogextract.1 @@ -0,0 +1,388 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMLOGEXTRACT 1 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmlogextract\f1 \- reduce, extract, concatenate +and merge Performance Co-Pilot archives +.SH SYNOPSIS +\f3pmlogextract\f1 +[\f3\-dfwz\f1] +[\f3\-c\f1 \f2configfile\f1] +[\f3\-S\f1 \f2starttime\f1] +[\f3\-s\f1 \f2samples\f1] +[\f3\-T\f1 \f2endtime\f1] +[\f3\-v\f1 \f2volsamples\f1] +[\f3\-Z\f1 \f2timezone\f1] +\f2input\f1 [...] \f2output\f1 +.SH DESCRIPTION +.B pmlogextract +reads one or more Performance Co-Pilot (PCP) archive logs +identified by +.I input +and creates a temporally merged and/or reduced PCP archive log in +.IR output . +The nature of merging is controlled by the number of input +archive logs, while the nature of data reduction is controlled by +the command line arguments. The input(s) must be PCP archive logs +created by +.BR pmlogger (1) +with performance data collected from the +.B same +host, but usually over different time periods and possibly (although +not usually) with different performance metrics being logged. +.PP +If only one +.I input +is specified, then the default behavior simply copies the input +PCP archive log, into the output PCP archive log. When two or +more PCP archive logs are specified as +.IR input , +the logs are merged (or concatenated) and written to +.IR output . +.PP +In the output archive log a ``mark'' record will be inserted at a time +just past the end of each of the input archive logs to indicate +a possible temporal discontinuity between the end of one input +archive log and the start of the next input archive log. +See the +.B "MARK RECORDS" +section below for more information. +There is no ``mark'' +record after the end of the +.I last +(in temporal order) of the input archive logs. +.SH COMMAND LINE OPTIONS +The command line options for +.B pmlogextract +are as follows: +.PP +.TP 7 +.BI \-c " configfile" +Extract only the metrics specified in +.I configfile +from the +.I input +PCP archive log(s). The +.I configfile +syntax accepted by +.B pmlogextract +is explained in more detail in the +.B Configuration File Syntax +section. +.PP +.TP 7 +.B \-d +Desperate mode. Normally if a fatal error occurs, all trace of +the partially written PCP archive +.I output +is removed. With the +.B \-d +option, the +.I output +archive log is not removed. +.PP +.TP 7 +.B \-f +For most common uses, all of the +input archive logs will have been collected in the same timezone. +But if this is not the case, then +.B pmlogextract +must choose one of the timezones from the input archive logs to be +used as the timezone for the output archive log. +The default is to use the timezone from the +.I last +input archive log. +The +.B \-f +option forces the timezone from the +.I first +input archive log to be used. +.TP 7 +.BI \-S " starttime" +Define the start of a time window to restrict the samples retrieved +or specify a ``natural'' alignment of the output sample times; refer +to +.BR PCPIntro (1). +See also the +.B \-w +option. +.PP +.TP 7 +.BI \-s " samples" +The argument +.I samples +defines the number of samples to be written to +.IR output . +If +.I samples +is 0 or +.B -s +is not specified, +.B pmlogextract +will sample until the end of the PCP archive log, +or the end of the time window as specified by +.BR -T , +whichever comes first. The +.B -s +option will override the +.B -T +option if it occurs sooner. +.PP +.TP 7 +.BI \-T " endtime" +Define the termination of a time window to restrict the samples +retrieved or specify a ``natural'' alignment of the output sample +times; refer to +.BR PCPIntro (1). +See also the +.B \-w +option. +.PP +.TP 7 +.BI \-v " volsamples" +The +.I output +archive log is potentially a multi-volume data set, and the +.B \-v +option causes +.B pmlogextract +to start a new volume after +.I volsamples +log records have been written to the archive log. +.RS 7 +.PP +Independent of any +.B \-v +option, each volume of an archive is limited to no more than +2^31 bytes, so +.I pmlogextract +will automatically create a new volume for the archive before +this limit is reached. +.RE +.PP +.TP 7 +.B \-w +Where +.B \-S +and +.B \-T +specify a time window within the same day, the +.B \-w +flag will cause the data within the time window to be extracted, +for every day in the archive log. +For example, the options +.B \-w \-S "@11:00" \-T "@15:00" +specify that +.B pmlogextract +should include archive log records only for the periods from 11am +to 3pm on each day. When +.B \-w +is used, the +.I output +archive log will contain ``mark'' records to indicate the temporal +discontinuity between the end of one time window and the start of +the next. +.PP +.TP 7 +.BI \-Z " timezone" +Use +.I timezone +when displaying the date and time. +.I Timezone +is in the format of the environment variable +.B TZ +as described in +.BR environ (5). +.PP +.TP 7 +.B \-z +Use the local timezone of the host from the input archive logs. +The default is to initially use the timezone of the local host. +.SH CONFIGURATION FILE SYNTAX +The +.I configfile +contains metrics of interest, listed one per line. Instances +may also be specified, but they are optional. The format for +each metric name is + + metric [[instance[,instance...]]] + +where +.I metric +may be a leaf or a non-leaf node in the Performance Metrics +Namespace (PMNS, see +.BR pmns (5)). +If a metric refers to a non-leaf node in the PMNS, +.B pmlogextract +will recursively descend the PMNS and include all metrics +corresponding to descendent leaf nodes. Instances are +optional, and may be specified as a list of one or more +space (or comma) separated names, numbers or strings. +Elements in the list that are numbers are assumed to be external +instance identifiers - see +.BR pmGetInDom (3) +for more information. +If no instances are given, then the logging specification is applied +to all instances of the associated metric(s). +.SH CONFIGURATION FILE EXAMPLE +This is an example of a valid +.IR configfile : +.PP + # + # config file for pmlogextract + # + + kernel.all.cpu + kernel.percpu.cpu.sys ["cpu0","cpu1"] + disk.dev ["dks0d1"] +.SH MARK RECORDS +When more than one input archive log contributes performance data to the +output archive log, then ``mark'' records are inserted to indicate a possible +discontinuity in the performance data. +.PP +A ``mark'' record contains a timestamp and no performance data and +is used to indicate that there is a time period +in the PCP archive log where we do not know the values of +.B any +performance metrics, because there was no +.BR pmlogger (1) +collecting performance data during this period. Since these periods are +often associated with the restart of a service or +.BR pmcd (1) +or a system, there may be considerable doubt as to the continuity of +performance data across this time period. +.PP +The rationale behind ``mark'' records may be demonstrated with an example. +Consider one input archive log that starts at 00:10 and ends at 09:15 on the +same day, and another input archive log that starts at 09:20 on the +same day and ends at 00:10 the following morning. The would be a very +common case for archives managed and rotated by +.BR pmlogger_check (1) +and +.BR pmlogger_daily (1). +.PP +The output archive log would contain: +.ta 12n +.br +00:10.000 first record from first input archive log +.br +\&... +.br +09:15.000 last record from first input archive log +.br +09:15.001 <mark record> +.br +09:20.000 first record from second input archive log +.br +\&... +.br +01:10.000 last record from second input archive log +.PP +The time period where the performance data is missing starts just after +09:15 and ends just before 09:20. +When the output archive log is processed with any of the PCP reporting +tools, the ``mark'' record is used to indicate a period of missing +data. For example in the archive above, if one was reporting the average +I/O rate at 30 minute intervals, aligned on the hour, then there would be +data for the intervals ending at 09:00 and 10:00 but no data reported for +the interval ending at 09:30 as this spans a ``mark'' record. +.PP +The presence of ``mark'' records in a PCP archive log can be established +using +.BR pmdumplog (1) +where a timestamp and the annotation +.B <mark> +is used to indicate a ``mark'' record. +.SH FILES +.PD 0 +For each of the +.I input +and +.I output +archive logs, several physical files are used. +.TP 10 +\f2archive\f3.meta +metadata (metric descriptions, instance domains, etc.) for the archive log +.TP +\f2archive\f3.0 +initial volume of metrics values (subsequent volumes have suffixes +.BR 1 , +.BR 2 , +\&...) \- for +.I input +these files may have been previously compressed with +.BR bzip2 (1) +or +.BR gzip (1) +and thus may have an additional +.B .bz2 +or +.B .gz +suffix. +.TP +\f2archive\f3.index +temporal index to support rapid random access to the other files in the +archive log. +.PD +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.I /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). +.SH SEE ALSO +.BR PCPIntro (1), +.BR pmdumplog (1), +.BR pmlc (1), +.BR pmlogger (1), +.BR pmlogreduce (1), +.BR pcp.conf (5) +and +.BR pcp.env (5). +.SH DIAGNOSTICS +All error conditions detected by +.B pmlogextract +are reported on +.I stderr +with textual (if sometimes terse) explanation. +.PP +Should one of the input archive logs be corrupted (this can happen +if the +.B pmlogger +instance writing the log suddenly dies), then +.B pmlogextract +will detect and report the position of the corruption in the file, +and any subsequent information from that archive log will not be processed. +.PP +If any error is detected, +.B pmlogextract +will exit with a non-zero status. +.SH CAVEATS +The preamble metrics (pmcd.pmlogger.archive, pmcd.pmlogger.host, +and pmcd.pmlogger.port), which are automatically recorded by +.B pmlogger +at the start of the archive, may not be present in the archive output by +.BR pmlogextract . +These metrics are only relevant while the archive is being created, +and have no significance once recording has finished. diff --git a/man/man1/pmlogger.1 b/man/man1/pmlogger.1 new file mode 100644 index 0000000..75b0bf9 --- /dev/null +++ b/man/man1/pmlogger.1 @@ -0,0 +1,761 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000 Silicon Graphics, Inc. All Rights Reserved. +.\" Copyright (c) 2014 Red Hat, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMLOGGER 1 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmlogger\f1 \- create archive log for performance metrics +.SH SYNOPSIS +\f3pmlogger\f1 +[\f3\-c\f1 \f2configfile\f1] +[\f3\-h\f1 \f2host\f1] +[\f3\-l\f1 \f2logfile\f1] +[\f3\-L\f1] +[\f3\-m\f1 \f2note\f1] +[\f3\-n\f1 \f2pmnsfile\f1] +[\f3\-P\f1] +[\f3\-r\f1] +[\f3\-s\f1 \f2endsize\f1] +[\f3\-t\f1 \f2interval\f1] +[\f3\-T\f1 \f2endtime\f1] +[\f3\-u\f1] +[\f3\-U\f1 \f2username\f1] +[\f3\-v\f1 \f2volsize\f1] +[\f3\-V\f1 \f2version\f1] +[\f3\-x\f1 \f2fd\f1] +[\f3\-y\f1] +\f2archive\f1 +.SH DESCRIPTION +.B pmlogger +creates the archive logs of performance metric values +that may be ``played back'' by other Performance Co-Pilot (see +.BR PCPIntro (1)) +tools. These logs form the basis of the VCR paradigm and retrospective +performance analysis services common to the PCP toolkit. +.PP +The mandatory argument +.I archive +is the base name for the physical files that constitute +an archive log. +.PP +The +.B \-V +option specifies the version for the archive that is generated. +By default a version 2 archive is generated, and the only value +currently supported for +.I version +is 2. +.PP +Unless directed to another host by the +.B \-h +option, +.B pmlogger +will contact the Performance Metrics Collector Daemon +(PMCD) on the local host and use that as the source of the metric +values to be logged. +.PP +To support the required flexibility and control over what is logged and +when, +.B pmlogger +maintains an independent two level logging state for each instance +of each performance metric. +At the first (mandatory) level, logging is +allowed to be +.B on +(with an associated interval between samples), or +.B off +or +.BR maybe . +In the latter case, the second (advisory) level logging is allowed +to be +.B on +(with an associated interval between samples), or +.BR off . +.PP +The +mandatory level allows universal specification that some metrics must be +logged, or must +.B not +be logged. The default state for all instances of all metrics when +.B pmlogger +starts is mandatory maybe and advisory off. +.PP +Use +.BR pmlc (1) +to interrogate and change the logging state once +.B pmlogger +is running. +.PP +If a metric's state is mandatory (on or off) and a request is made to change it +to mandatory maybe, the new state is mandatory maybe and advisory off. If a +metric's state is already advisory (on or off) and a request is made to change +it to mandatory maybe, the current state is retained. +.PP +It is not possible for +.B pmlogger +to log specific instances of a metric and all instances of the same metric +concurrently. If specific instances are being logged and a request to log all +instances is made, then all instances of the metric will be logged according to +the new request, superseding any prior logging request for the metric. A +request to log all instances of a metric will supersede any previous request to +log all instances. A request to log specific instances of a metric when all +instances are already being logged is refused. To do this one must turn off +logging for all instances of the metric first. In each case, the validity of +the request is checked first; for example a request to change a metric's +logging state to advisory on when it is currently mandatory off is never +permitted (it is necessary to change the state to mandatory maybe first). +.PP +Optionally, each system running +.BR pmcd (1) +may also be configured to run a ``primary'' +.B pmlogger +instance. +Like +.BR pmcd (1), +this +.B pmlogger +instance is launched by +.BR $PCP_RC_DIR/pcp , +and is affected by the files +.I $PCP_SYSCONF_DIR/pmlogger +(use +.BR chkconfig (8) +to activate or disable the primary +.B pmlogger +instance), +.I $PCP_SYSCONF_DIR/pmlogger/pmlogger.options +(command line options passed to the primary +.BR pmlogger ) +and +.I $PCP_SYSCONF_DIR/pmlogger/config.default +(the default initial configuration file for the primary +.BR pmlogger ). +.PP +The primary +.B pmlogger +instance is identified by the +.B \-P +option. There may be at most one ``primary'' +.B pmlogger +instance on each system with an active +.BR pmcd (1). +The primary +.B pmlogger +instance (if any) +must be running on the same host as the +.BR pmcd (1) +to which it connects, so the +.B \-h +and +.B \-P +options are mutually exclusive. +.PP +When launched as a non-primary instance, +.B pmlogger +will exit immediately if the configuration +file causes no metric logging to be scheduled. The +.B \-L +option overrides this behavior, and causes a non-primary +.B pmlogger +instance to ``linger'', presumably pending some future +dynamic re-configuration and state change via +.BR pmlc (1). +.B pmlogger +will also linger without the +.B \-L +option being used if all the metrics to be logged are logged +as once only metrics. When the once only metrics have been +logged, a warning message will be generated stating +that the event queue is empty and no more events will be scheduled. +.PP +By default all diagnostics and errors from +.B pmlogger +are written to the file +.I pmlogger.log +in the directory where +.B pmlogger +is launched. +The +.B \-l +option may be used to override the default behavior. +If the log file cannot be created or is not writable, output is +written to standard error instead. +.PP +If specified, the +.B \-s +option instructs +.B pmlogger +to terminate after a certain size in records, bytes or time units +has been accumulated. +If +.IR endsize +is an integer then +.IR endsize +records will be written to the log. +If +.IR endsize +is an integer suffixed by +.B b +or +.B bytes +then +.IR endsize +bytes of the archive data will be written out +(note, however, that archive log record boundaries will not be broken and +so this limit may be slightly surpassed). +Other viable file size units include: +.BR K , +.BR Kb , +.BR Kbyte , +.BR Kilobyte +for kilobytes and +.BR M , +.BR Mb , +.BR Mbyte , +.BR Megabyte +for megabytes and +.BR G , +.BR Gb , +.BR Gbyte , +.BR Gigabyte +for gigabytes. +These units may be optionally suffixed by an +.B s +and may be of mixed case. +Alternatively +.IR endsize +may be an integer or a floating point number suffixed using a time unit +as described in +.BR PCPIntro (1) +for the +.I interval +argument (to the standard PCP +.BR \-t +command line option). +.nf +Some examples of different formats: +.in 1i +.B \-s 100 +.B \-s 100bytes +.B \-s 100K +.B \-s 100Mb +.B \-s 10Gbyte +.B \-s 10mins +.B \-s 1.5hours +.in +.fi +The default is for +.B pmlogger +to run forever. +.PP +The +.B \-r +option causes the size of the physical record(s) for each +group of metrics and the expected contribution of +the group to the size of the PCP archive for one full day +of collection to be reported in the log file. This +information is reported +the first time each group is successfully written +to the archive. +.PP +The +.B \-U +option specifies the user account under which to run +.BR pmlogger . +The default is the current user account for interactive use. +When run as a daemon, the unprivileged "pcp" account is used +in current versions of PCP, but in older versions the superuser +account ("root") was used by default. +.PP +The log file is potentially a multi-volume data set, and the +.B \-v +option causes +.B pmlogger +to start a new volume after a certain size in records, bytes, +or time units has been accumulated for the current volume. +The format of this size specification is identical to that +of the +.B \-s +option (see above). +The default is for +.B pmlogger +to create a single volume log. +Additional volume switches can also be forced asynchronously by +either using +.BR pmlc (1) +or sending +.B pmlogger +a SIGHUP signal (see below). Note, if a scheduled volume +switch is in operation due to the +.B \-v +option, then its counters will be reset after an +asynchronous switch. +.PP +Independent of any +.B \-v +option, each volume of an archive is limited to no more than +2^31 bytes, so +.I pmlogger +will automatically create a new volume for the archive before +this limit is reached. +.PP +Normally +.B pmlogger +operates on the distributed Performance Metrics Name Space (PMNS), +however if the +.B \-n +option is specified an alternative local PMNS is loaded +from the file +.IR pmnsfile. +.PP +Under normal circumstances, +.B pmlogger +will run forever (except for a +.B \-s +option or a termination signal). +The +.B \-T +option may be used to limit the execution time using the format +of time as prescribed by +.BR PCPIntro (1). +The time is interpreted within the time zone of the PMCD server, +unless the +.B \-y +option is given, within which case the time zone at this logger +host is used. +.nf +Some examples of different formats: +.in 1i +.B \-T 10mins +.B \-T '@ 11:30' +.in +.fi +From this it can be seen that +.B \-T 10mins +and +.B \-s 10mins +perform identical actions. +.PP +When +.B pmlogger +receives a SIGHUP signal, the current volume of the log is closed, and +a new volume is opened. This mechanism (or the alternative mechanism +via +.BR pmlc (1)) +may be used to manage the growth of the log files \- once a log volume +is closed, that file may be archived without ill-effect on the +continued operation of +.BR pmlogger . +See also the +.B \-v +option above. +.PP +Historically the buffers for the current log may be flushed to disk using the +\f3flush\f1 command of +.BR pmlc (1), +or by sending +.B pmlogger +a SIGUSR1 signal +or by using the +.B \-u +option. +The current version of +.I pmlogger +and the +.I libpcp +routines that underpin +.I pmlogger +unconditionally use unbuffered writes and a single +.BR fwrite (3) +for each logical record written, and so ``flushing'' does not +force any additional data to be written to the file system. +The +.B \-u +option, the SIGUSR1 handling and the +.BR pmlc (1) +.B flush +command are retained for backwards compatibility. +.P +When launched with the +.B \-x +option, pmlogger will accept asynchronous +control requests on the file descriptor \f2fd\f1. This option is only +expected to be used internally by PCP applications that support ``live +record mode''. +.P +The +.B \-m +option allows the string +.I note +to be appended to the map file for this instance of +.B pmlogger +in the +.B $PCP_TMP_DIR/pmlogger +directory. +This is currently used internally to document the file descriptor (\c +.IR fd ) +when the +.B \-x +option is used, or to indicate that this +.B pmlogger +instance was started under the control of +.BR pmlogger_check (1). +.SH CONFIGURATION FILE SYNTAX +The configuration file may be specified with the +.B \-c +option. If it is not, configuration specifications are read from standard +input. +.PP +If +.I configfile +does not exist, then a search is made in the directory +.I $PCP_SYSCONF_DIR/pmlogger +for a file of the same name, and if found that file is used, +e.g. if +.I config.mumble +does not exist in the current directory and +the file +.I $PCP_SYSCONF_DIR/pmlogger/config.mumble +does exist, then +.B "\-c config.mumble" +and +.B "\-c $PCP_SYSCONF_DIR/pmlogger/config.mumble" +are equivalent. +.PP +The syntax for the configuration file is as follows. +.IP 1. 5n +Words are separated by white space (space, tab or newline). +.IP 2. 5n +The symbol ``#'' (hash) introduces a comment, and all text up +to the next newline +is ignored. +.IP 3. 5n +Keywords (shown in +.B bold +below) must appear literally (i.e. in lower case). +.IP 4. 5n +Each specification begins with the optional keyword +.BR log , +followed by one of the states +.BR "mandatory on" , +.BR "mandatory off" , +.BR "mandatory maybe" , +.BR "advisory on" +or +.BR "advisory off" . +.IP 5. 5n +For the +.B on +states, a logging interval must follow using the syntax ``\c +.BR once '', +or ``\c +.BR default '', +or ``\c +.B every +.IR "N timeunits" '', +or simply ``\c +.IR "N timeunits" '' +\- +.I N +is an unsigned integer, and +.I timeunits +is one of the keywords +.BR msec , +.BR millisecond , +.BR sec , +.BR second , +.BR min , +.BR minute , +.BR hour +or the plural form of one of the above. +.sp 0.5v +Internal limitations require the +interval +to be smaller than (approximately) +74 hours. An +interval +value of zero is a synonym for +.BR once . +An interval of +.B default +means to use the default logging interval of +60 seconds; this default value may be changed to +.I interval +with the +.B \-t +command line option. +.IP "" +The +.I interval +argument follows the syntax described in +.BR PCPIntro (1), +and in the simplest form may be an unsigned integer (the implied +units in this case are seconds). +.IP 6. 5n +Following the state and possible interval specifications comes +a ``{'', followed by a list of one or more metric specifications +and a closing ``}''. +The list is white space (or comma) separated. +If there is only one metric specification in the list, the braces are optional. +.IP 7. 5n +A metric specification consists of a metric name optionally +followed by a set of instance names. +The metric name follows the standard PCP naming conventions, see +.BR pmns (5), +and if the metric name +is a non-leaf node in the PMNS (see \c +.BR pmns (5)), +then +.B pmlogger +will recursively descend the PMNS and apply the logging specification +to all descendent metric names that are leaf nodes in the PMNS. +The set of instance names +is a ``['', followed by a list +of one or more space (or comma) separated +names, numbers or strings, and a closing ``]''. +Elements in the list that are numbers are assumed to be +internal instance identifiers, other elements are assumed to +be external instance identifiers \- see +.BR pmGetInDom (3) +for more information. +.RS +.PP +If no instances are given, then the logging specification +is applied to all instances of the associated metric. +.RE +.IP 8. 5n +There may be an arbitrary number of logging specifications. +.IP 9. 5n +Following all of the logging specifications, there may be an optional +access control section, introduced by the literal token +.BR [access] . +Thereafter come access control rules that allow or disallow operations +from particular hosts or groups of hosts. +.RS 5n +.PP +The operations may be used to interrogate or control a running +.B pmlogger +using +.BR pmlc (1) +and fall into the following classes: +.TP 15 +.B enquire +interrogate the status of +.B pmlogger +and the metrics it is logging +.PD 0 +.TP 15 +.B advisory +Change advisory logging. +.TP 15 +.B mandatory +Change mandatory logging. +.TP +.B all +All of the above. +.PD +.PP +Access control rules are of the form ``\c +.B allow +.I hostlist +.B : +.I operationlist +.BR ; '' +and ``\c +.B disallow +.I hostlist +.B : +.I operationlist +.BR ; ''. +.PP +The +.I hostlist +follows the syntax and semantics for the access control mechanisms +used by PMCD and are fully documented in +.BR pmcd (1). +An +.I operationslist +is a comma separated list of the operations +.BR advisory , +.BR mandatory , +.B enquire +and +.BR all . +.PP +A missing +.BR [access] +section allows all access and is equivalent to +.BR "allow * : all;" . +.RE +.SH EXAMPLES +For each PCP utility, there is a sample +.B pmlogger +configuration file that could be used to create an archive log suitable +for replaying with that tool (i.e. includes all of the performance +metrics used by the tool). +For a tool named +.I foo +this configuration file is located in +.IR $PCP_SYSCONF_DIR/pmlogger/config.foo . +.PP +The following is a simple default configuration file for a primary +.B pmlogger +instance, and demonstrates most of the capabilities of the +configuration specification language. +.PP +.in +0.5i +.nf +.ft CW +log mandatory on once { hinv.ncpu hinv.ndisk } +log mandatory on every 10 minutes { + disk.all.write + disk.all.read + network.interface.in.packets [ "et0" ] + network.interface.out.packets [ "et0" ] + nfs.server.reqs [ "lookup" "getattr" "read" "write" ] +} + +log advisory on every 30 minutes { + environ.temp + pmcd.pdu_in.total + pmcd.pdu_out.total +} + +[access] +disallow * : all except enquire; +allow localhost : mandatory, advisory; +.ft R +.fi +.in +.SH FILES +.PD 0 +.TP 10 +\f2archive\f3.meta +metadata (metric descriptions, instance domains, etc.) for the archive log +.TP +\f2archive\f3.0 +initial volume of metrics values (subsequent volumes have suffixes +.BR 1 , +.BR 2 , +\&...) +.TP +\f2archive\f3.index +temporal index to support rapid random access to the other files in the +archive log +.TP +.B $PCP_TMP_DIR/pmlogger +.B pmlogger +maintains the files in this directory as the map between the +process id of the +.B pmlogger +instance and the +IPC port that may be used to control +each +.B pmlogger +instance (as used by +.BR pmlc (1)) +.TP +.B $PCP_SYSCONF_DIR/pmlogger/config.default +default configuration file for the primary logger instance +launched from +.B $PCP_RC_DIR/pcp +.TP +.BR $PCP_SYSCONF_DIR/pmlogger/config. * +assorted configuration files suitable for creating logs that may +be subsequently replayed with the PCP visualization and monitoring +tools +.TP +.BI $PCP_LOG_DIR/pmlogger/ hostname +Default directory for PCP archive files for performance +metric values collected from the host +.IR hostname . +.TP +.I \&./pmlogger.log +(or +.B $PCP_LOG_DIR/pmlogger/\fIhostname\fB/pmlogger.log +when started automatically by either +.B $PCP_RC_DIR/pcp +or one of the +.BR pmlogger (1) +monitoring scripts such as +.BR pmlogger_check (1)) +.br +all messages and diagnostics are directed here +.TP +.B $PCP_RC_DIR/pcplocal +contains ``hooks'' to enable automatic restart at system boot time +.PD +.SH ENVIRONMENT +Normally +.B pmlogger +creates a socket to receive control messages from +.BR pmlc (1) +on the first available TCP/IP port numbered 4330 or higher. The environment +variable +.B PMLOGGER_PORT +may be used to specify an alternative starting port number. +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.I /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). +.SH SEE ALSO +.BR PCPIntro (1), +.BR pmcd (1), +.BR pmdumplog (1), +.BR pmlc (1), +.BR pmlogger_check (1), +.BR pcp.conf (5), +.BR pcp.env (5), +.BR pmns (5) +and +.BR chkconfig (8). +.SH DIAGNOSTICS +The archive logs are sufficiently precious that +.B pmlogger +will not truncate an existing physical file. A message of the form +.br +.in +0.5v +__pmLogNewFile: "foo.index" already exists, not over-written +.br +__pmLogCreate: File exists +.in +indicates this situation has arisen. You must explicitly remove +the files and launch +.B pmlogger +again. +.PP +There may be at most one primary +.B pmlogger +instance per monitored host; attempting to bend this rule produces the error: +.br +.in +0.5v +pmlogger: there is already a primary pmlogger running +.in +.PP +Various other messages relating to the creation and/or deletion of +files in +.I $PCP_TMP_DIR/pmlogger +suggest a permission problem on this directory, or some feral +files have appeared therein. diff --git a/man/man1/pmlogger_check.1 b/man/man1/pmlogger_check.1 new file mode 100644 index 0000000..4554b92 --- /dev/null +++ b/man/man1/pmlogger_check.1 @@ -0,0 +1,528 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2013-2014 Red Hat. +.\" Copyright (c) 2000 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMLOGGER_CHECK 1 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmlogger_check\f1, +\f3pmlogger_daily\f1, +\f3pmlogger_merge\f1 \- administration of Performance Co-Pilot archive log files +.SH SYNOPSIS +.B $PCP_BINADM_DIR/pmlogger_check +[\f3\-CNsTV\f1] +[\f3\-c\f1 \f2control\f1] +.br +.B $PCP_BINADM_DIR/pmlogger_daily +[\f3\-NorV\f1] +[\f3\-c\f1 \f2control\f1] +[\f3\-k\f1 \f2discard\f1] +[\f3\-m\f1 \f2addresses\f1] +[\f3\-s\f1 \f2size\f1] +[\f3\-t\f1 \f2want\f1] +[\f3\-x\f1 \f2compress\f1] +[\f3\-X\f1 \f2program\f1] +[\f3\-Y\f1 \f2regex\f1] +.br +.B $PCP_BINADM_DIR/pmlogger_merge +[\f3\-fNV\f1] +[\f2input-basename\f1 ... \f2output-name\f1] +.br +.SH DESCRIPTION +This series of shell scripts and associated control files may be used to +create a customized regime of administration and management for +Performance Co-Pilot (see +.BR PCPintro (1)) +archive log files. +.PP +The +.B \-V +option that is common to all the scipts will enable verbose tracing and +reporting. +By default the scripts generate no output unless some error or warning condition is +encountered. +.PP +The common +.B \-N +option enables a ``show me'' mode, where the actions are echoed, +but not executed, in the style of ``make \-n''. +Using +.B \-N +in conjunction with +.B \-V +maximizes the diagnostic capabilities for debugging. +.PP +.B pmlogger_daily +is intended to be run once per day, preferably in the early morning, as +soon after midnight as practicable. Its task is to aggregate and rotate +one or more sets of PCP archives. +After some period, old PCP archives are discarded. This period is +14 days by default, but may be changed using the +.B \-k +option. Two special values are recognized for the period (\c +.IR discard ), +namely +.B 0 +to keep no archives beyond the current one, and +.B forever +to prevent any archives being discarded. +.PP +Archive data files can optionally be compressed after some period +to conserve disk space. This is particularly useful for large numbers of +.B pmlogger +processes under the control of +.BR pmlogger_check . +By default no compression is done. +The +.B \-x +option enables compression and +specifies the number of days after which to compress archive data +files, and the +.B \-X +option specifies the program to use for compression \- by default this is +.BR xz (1). +Use of the +.B \-Y +option allows a regular expression to be specified causing files in +the set of files matched for compression to be omitted \- this allows +only the data file to be compressed, and also prevents the program from +attempting to compress it more than once. The default +.I regex +is "\.(meta|index|Z|gz|bz2|zip|xz|lzma|lzo|lz4)$" \- such files are +filtered using the +.B \-v +option to +.BR egrep (1). +.PP +To accommodate the evolution of PMDAs and changes in production +logging environments, +.B pmlogger_daily +is integrated with +.BR pmlogrewrite (1) +to allow optional and automatic rewriting of archives before merging. +If there are global rewriting rules to be applied across all archives +mentioned in the control file, then create the directory +.B $PCP_SYSCONF_DIR/pmlogrewrite +and place any +.BR pmlogrewrite (1) +rewriting rules in this directory. +For rewriting rules that are specific to only one family of archives, +use the directory name from the control file (the +.I fourth +field) and create a file, or a directory, or a symbolic link named +.B pmlogrewrite +within this directory +and place the required rewriting rule(s) in the +.B pmlogrewrite +file or in files +within the +.B pmlogrewrite +subdirectory. +.B pmlogger_daily +will choose rewriting rules from the archive directory if they +exist, else rewriting rules from +.B $PCP_SYSCONF_DIR/pmlogrewrite +if that directory exists, else no rewriting is attempted. +.PP +The +.B \-r +command line option acts as an over-ride and +prevents all archive rewriting with +.BR pmlogrewrite (1) +independent of the presence of any rewriting rule files or directories. +.PP +By default all possible archives will be merged. The +.B \-o +option reinstates the old behaviour in which only yesterday's archives +will be considered as merge candidates. +.PP +In the special case where only a single input archive +needs to be merged, +.BR pmlogmv (1) +is used to rename the archive, rather than copy the input archive +using +.BR pmlogger_merge . +.PP +The +.B \-M +option may be used to disable archive merging (or renaming) and rewriting +(\c +.B \-M +implies +.BR \-r ). +This is most useful in cases where the archives are being incrementally +copied to a remote repository, e.g. using +.BR rsync (1). +Merging, renaming and rewriting all risk an increase in the synchronization +load, especially immediately after +.B pmlogger_daily +has run, so +.B \-M +may be useful in these cases. +.PP +To assist with debugging or diagnosing intermittent failures the +.B \-t +option may be used. This will turn on very verbose tracing (\c +.BR \-VV ) +and capture the trace output in a file named +.BI $PCP_LOG_DIR/pmlogger/daily. datestamp .trace, +where +.I datestamp +is the time +.B pmlogger_daily +was run in the format YYYYMMDD.HH.MM. +In addition, the +.I want +argument will ensure that trace files created with +.B \-t +will be kept for +.I want +days and then discarded. +.PP +In addition, if the +PCP ``notices'' file (\c +.BR $PCP_LOG_DIR/NOTICES ) +is larger than 20480 bytes, +.B pmlogger_daily +will rename the file with a ``.old'' suffix, and start +a new ``notices'' file. +The rotate threshold may be changed from 20480 to +.I size +bytes using the +.B \-s +option. +.PP +Use of the +.B \-m +option causes +.B pmlogger_daily +to construct a summary of the ``notices'' file entries which were +generated in the last 24 hours, and e-mail that summary to the set of +space-separated +.IR addresses . +This daily summary is stored in the file +.BR $PCP_LOG_DIR/NOTICES.daily , +which will be empty when no new ``notices'' entries were made in the previous +24 hour period. +.PP +The script +.B $PCP_BINADM_DIR/pmlogger_daily +could be copied and modified to implement a site-specific procedure for +end-of-week and/or end-of-month management for a set of PCP archives. +.PP +.B pmlogger_check +may be run at any time, and is intended to check that the desired set +of +.BR pmlogger (1) +processes are running, and if not to re-launch any failed loggers. +Use of the +.B \-s +option provides the reverse functionality, allowing the set of +.B pmlogger +processes to be cleanly shutdown. +Use of the +.B \-C +option queries the system service runlevel information for +.BR pmlogger , +and uses that to determine whether to start or stop processes. +.PP +The +.B \-T +option provides a terser form of output for +.B pmlogger_check +that is most suitable for a +.I pmlogger +\&``farm'' where many instances of +.I pmlogger +are expected to be running. +.PP +.B pmlogger_merge +is a wrapper script for +.BR pmlogextract (1) +that merges all of the archive logs matching the +.I input-basename +arguments, and creates a new archive using +.I output-name +as the base name for the physical files that constitute +an archive log. +The +.I input-basename +arguments may contain meta characters in the style of +.BR sh (1). +If specified, the +.B \-f +option causes all of the input files to be removed once the output +archive has been created. +.PP +.B pmlogger_merge +is used by +.BR pmlogger_daily . +.PP +Both +.B pmlogger_daily +and +.B pmlogger_check +are controlled by a PCP logger control file +that specifies the +.B pmlogger +instances to be managed. The default control file is +.BR $PCP_PMLOGGERCONTROL_PATH , +but an alternate may be specified using the +.B \-c +option. +.PP +The control file should be customized according to the following rules +that define for the current version (1.1) +of the control file format. +.IP 1. +Lines beginning with a ``#'' are comments. +.PD 0 parameters of the +.IP 2. +Lines beginning with a ``$'' are assumed to be +assignments to environment variables in the style of +.BR sh (1), +and all text following the ``$'' will be +.BR eval 'ed +by the script reading the control file, +and the corresponding variable exported into the environment. +This is particularly +useful to set and export variables into the environment of +the administrative scripts, e.g. +.br +.in +4n +.ft CW +.nf +$ PMCD_CONNECT_TIMEOUT=20 +.fi +.ft R +.in -4n +.br +.BR Warning : +The +.B $PCP_PMLOGGERCONTROL_PATH +file must not be writable by any user other than root. +.br +.IP 3. +There +.B must +be a version line of the form: +.br +.in +4n +.ft CW +.nf +$ version=1.1 +.fi +.ft R +.in -4n +.IP 4. +There should be one line in the control file +for each +.B pmlogger +instance of the form: + +.in +4n +.ft CW +.nf +\f2host\f1 \f3y\f1|\f3n\f1 \f3y\f1|\f3n\f1 \f2directory\f1 \f2args\f1 +.fi +.ft R +.in -4n + +.IP 5. +Fields within a line of the control file +are separated by one or more spaces or tabs. +.IP 6. +The +.I first +field is the name of the host that is the source of the +performance metrics for this +.B pmlogger +instance. +.IP 7. +The +.I second +field indicates if this is a +.I primary +.B pmlogger +instance (\c +.BR y ) +or not (\c +.BR n ). +Since the primary logger must run on the local host, and there may be +at most one primary logger for a particular host, this field can be +.B y +for at most one +.B pmlogger +instance, in which case the host name must be the name of the local host. +.IP 8. +The +.I third +field indicates if this +.B pmlogger +instance needs to be started under the control of +.BR pmsocks (1) +to connect to a +.B pmcd +through a firewall (\c +.B y +or +.BR n ). +.IP 9. +The +.I fourth +field is a directory name. All files +associated with this +.B pmlogger +instance will be created in this directory, +and this will be the current directory for the execution of +any programs required in the maintenance of those archives. +A useful convention is that primary logger archives for the local host +with hostname +.I myhost +are maintained in the directory +.BI $PCP_LOG_DIR/pmlogger/ myhost +(this is where the default +.B pmlogger +start-up script in +.B $PCP_RC_DIR/pcp +will create the archives), while archives for the remote host +.I mumble +are maintained in +.BI $PCP_LOG_DIR/pmlogger/ mumble\fR. +.IP 10. +All other fields are interpreted as arguments to be passed to +.BR pmlogger (1) +and/or +.BR pmnewlog (1). +Most typically this would be the +.B \-c +option. +.PD +.PP +The following sample control lines specify a primary logger +on the local host (\c +.IR bozo ), +and a non-primary logger to collect and log +performance metrics from the host +.IR boing . +.PP +.nf +.ft CW +$version=1.1 +bozo y n $PCP_LOG_DIR/pmlogger/bozo \-c config.default +boing n n $PCP_LOG_DIR/pmlogger/boing \-c ./pmlogger.config +.ft 1 +.fi +.PP +Typical +.BR crontab (5) +entries for periodic execution of +.B pmlogger_daily +and +.B pmlogger_check +are given in +.BR $PCP_SYSCONF_DIR/pmlogger/crontab +(unless installed by default in +.I /etc/cron.d +already) +and shown below. +.PP +.nf +.ft CW +# daily processing of archive logs +14 0 * * * $PCP_BINADM_DIR/pmlogger_daily +# every 30 minutes, check pmlogger instances are running +25,55 * * * * $PCP_BINADM_DIR/pmlogger_check +.ft 1 +.fi +.PP +The output from the +.BR cron (1) +execution of the scripts may be extended using the +.B \-V +option. + +.SH FILES +.TP 10 +.B $PCP_PMLOGGERCONTROL_PATH +the PCP logger control file +.br +.BR Warning : +this file must not be writable by any user other than root. +.TP +.B $PCP_SYSCONF_DIR/pmlogger/crontab +sample crontab for automated script execution by $PCP_USER (or root). +Exists only if the platform does not support the /etc/cron.d mechanism. +.TP +.B $PCP_SYSCONF_DIR/pmlogger/config.default +default +.B pmlogger +configuration file location for the local primary logger, typically +generated automatically by +.BR pmlogconf (1). +.TP +.BI $PCP_LOG_DIR/pmlogger/ hostname +default location for archives of performance information collected from the host +.I hostname +.TP +.BI $PCP_LOG_DIR/pmlogger/ hostname /lock +transient lock file to guarantee mutual exclusion during +.B pmlogger +administration for the host +.I hostname +\- if present, can be safely removed if neither +.B pmlogger_daily +nor +.B pmlogger_check +are running +.TP +.BI $PCP_LOG_DIR/pmlogger/ hostname /Latest +PCP archive folio created by +.BR mkaf (1) +for the most recently launched archive containing performance metrics from +the host +.I hostname +.TP +.B $PCP_LOG_DIR/NOTICES +PCP ``notices'' file used by +.BR pmie (1) +and friends +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.B /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). +.SH SEE ALSO +.BR egrep (1), +.BR PCPIntro (1), +.BR pmlc (1), +.BR pmlogconf (1), +.BR pmlogger (1), +.BR pmlogextract (1), +.BR pmlogmv (1), +.BR pmlogrewrite (1), +.BR pmnewlog (1), +.BR pmsocks (1), +.BR xz (1) +and +.BR cron (8). diff --git a/man/man1/pmloglabel.1 b/man/man1/pmloglabel.1 new file mode 100644 index 0000000..73173f7 --- /dev/null +++ b/man/man1/pmloglabel.1 @@ -0,0 +1,162 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2008 Aconex. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMLOGLABEL 1 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmloglabel\f1 \- check and repair a performance metrics archive label +.SH SYNOPSIS +\f3pmloglabel\f1 +[\f3\-Llsv\f1] +[\f3\-h\f1 \f2hostname\f1] +[\f3\-p\f1 \f2pid\f1] +[\f3\-V\f1 \f2version\f1] +[\f3\-Z\f1 \f2timezone\f1] +\f2archive\f1 +.SH DESCRIPTION +.B pmloglabel +verifies, reports on, and can modify all details of the labels in +each of the files of a Performance Co-Pilot (PCP) archive log. +The archive log has the base name +.I archive +and must have been previously created using +.BR pmlogger (1). +.PP +Each of the files in a PCP archive (metadata, temporal index, and one +or more data volumes) must contain a valid label at the start, else +the PCP tools will refuse to open the archive at all. +.PP +Thus, the primary function of +.B pmloglabel +is to be able to repair any inconsistent or corrupt label fields, such +that the entire archive is not lost. +It will not check the remainder of the archive, but it will give you a +fighting chance to recover otherwise lost data. +Together, +.B pmloglabel +and +.B pmlogextract +are able to produce a valid PCP archive from many forms of corruption. +.PP +Note that if the temporal index is found to be corrupt, the "*.index" file +can be safely moved aside and the archive will still be accessible, however +retrievals may take longer without the index. +.PP +The options control the specific information to be reported, or the +specific fields to be modified: +.TP 5 +.B \-h +Modify the logged +.I hostname +in the archive label, for all files in the archive. +.TP +.B \-l +Dump out the archive label, showing the log format version, +the time and date for the start and (current) end of the archive, and +the host from which the performance metrics values were collected. +.TP +.B \-L +Like +.BR \-l , +just a little more verbose, showing also the timezone and creator +process identifier from the archive label. +.TP +.B \-p +Set the process identifier stored in the archive label to +.IR pid , +for all files in the archive. +.TP +.B \-s +Rewrite the sentinel values which precede and follow the archive label, +for all files in the archive. +.TP +.B \-v +Verbose mode. Additional progress information is produced at each step. +.TP +.B \-V +Stamp the +.I version +number into the magic number field at the start of the archive label, +for all files in the archive. +.TP +.B \-Z +Changes the timezone in the archive labels to +.I timezone +in the format of the environment variable +.B TZ +as described in +.BR environ (5). +.PP +.SH EXAMPLES +The following demonstrates the use of +.B pmloglabel +in finding and then correcting a corrupt field (PID) in the label of the temporal index of +an archive named "20080125". +.PP +.sp 0.5v +.in +1i +.ft CW +.nf +$ pmdumplog \-l 20080125 +pmdumplog: Cannot open archive "20080125": Illegal label record at start of a PCP archive log file +$ pmloglabel 20080125 +Mismatched PID (5264/5011) between temporal index and data volume 0 +$ pmloglabel \-p 5264 20080125 +$ pmdumplog \-l 20080125 +Log Label (Log Format Version 2) +Performance metrics from host fw1 + commencing Fri Jan 25 00:10:09.341 2008 + ending Sat Jan 26 00:09:54.344 2008 +.fi +.SH EXIT STATUS +.B pmloglabel +exits with status 0 if the archive labels are clean. +If invoked incorrectly, the exit status will be 1. +If corruption is detected and still exists at the end, +the exit status will be 2. +If requested to write out the archive labels, and some aspect of that +write out fails, then the exit status will be 3. +.SH FILES +.PD 0 +.TP 10 +.BI $PCP_LOG_DIR/pmlogger/ hostname +Default directory for PCP archives containing performance +metric values collected from the host +.IR hostname . +.PD +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.I /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). +.SH SEE ALSO +.BR PCPIntro (1), +.BR pmlogcheck (1), +.BR pmlogextract (1), +.BR pmlogger (1), +.BR pmlogger_check (1), +.BR pmlogger_daily (1), +.BR pmlogrewrite (1), +.BR pcp.conf (5), +and +.BR pcp.env (5). diff --git a/man/man1/pmlogmv.1 b/man/man1/pmlogmv.1 new file mode 100644 index 0000000..6e5f4a9 --- /dev/null +++ b/man/man1/pmlogmv.1 @@ -0,0 +1,78 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2014 Ken McDonell. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMLOGMV 1 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmlogmv\f1 \- move (rename) Performance Co-Pilot archive files +.SH SYNOPSIS +\f3pmlogmv\f1 [\f2\-NV\f1] \f2oldname\f1 \f2newname\f1 +.SH DESCRIPTION +A Performance Co-Pilot (PCP) archive consists of mutiple files as +created by +.BR pmlogger (1). +.B pmlogmv +allows all the files of a single PCP archive +to be moved or renamed as a group in a single operation. +.PP +The +.I oldname +argument identifies the target archive, and may be either the basename +that is common to all files in that archive or one of the archive's +files. +The new archive's basename is +.IR newname . +.PP +The +.B \-N +option performs a dry-run, checking and reporting what changes would +be made without making any changes. +.PP +Additional reporting verbosity may be requested with the +.B \-V +option. +.PP +Because PCP archives are important records of system activity, special +care is taken to ensure the integrity of an archive's files. +For recoverable problems encountered during the execution of +.BR pmlogmv , +all the files associated with +.I oldname +will be preserved, and no new files with the +.I newname +prefix will be created. +``Recoverable problems'' include signals that can be caught (such as SIGHUP, +SIGINT, SIGQUIT and SIGTERM), permissions issues, new files already existing, +file system full events, etc. +.PP +The implementation of +.B pmlogmv +uses hard links in the file system and so follows the semantic +restrictions of +.IR ln (2) +which for most systems means the directories containing both +the +.I oldname +and the +.I newname +PCP archive files need to be writeable and within the +.B same +file system. +.SH "SEE ALSO" +.BR ln (2) +and +.BR pmlogger (1). +.SH DIAGNOSTICS +All error and warning messages are intended to be easily understood and errors +produce a non-zero exit status. diff --git a/man/man1/pmlogreduce.1 b/man/man1/pmlogreduce.1 new file mode 100644 index 0000000..4b3be60 --- /dev/null +++ b/man/man1/pmlogreduce.1 @@ -0,0 +1,327 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMLOGREDUCE 1 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmlogreduce\f1 \- temporal reduction of Performance Co-Pilot archives +.SH SYNOPSIS +\f3$PCP_BINADM_DIR/pmlogreduce\f1 +[\f3\-z\f1] +[\f3\-A\f1 \f2align\f1] +[\f3\-S\f1 \f2starttime\f1] +[\f3\-s\f1 \f2samples\f1] +[\f3\-T\f1 \f2endtime\f1] +[\f3\-t\f1 \f2interval\f1] +[\f3\-v\f1 \f2volsamples\f1] +[\f3\-Z\f1 \f2timezone\f1] +\f2input\f1 \f2output\f1 +.SH DESCRIPTION +.B pmlogreduce +reads one Performance Co-Pilot (PCP) archive +identified by +.I input +(this must be a PCP archive created by +.BR pmlogger (1), +.BR pmlogextract (1) +or +.BR pmlogreduce (1)), +and creates a temporally reduced PCP archive in +.IR output . +The +data reduction involves statistical and temporal reduction of samples with +an output sampling +interval defined by the +.B \-t +option in the +.I output +archive (independent of the sampling intervals in the +.I input +archive), and is further controlled by +other command line arguments. +.PP +For some metrics, temporal data reduction is not going to be helpful, +so for metrics with types +.B PM_TYPE_AGGREGATE +or +.BR PM_TYPE_EVENT , +a warning is issued if these metrics are found in +.I input +and they will be skipped and not appear in the +.I output +archive. +.SH COMMAND LINE OPTIONS +The command line options for +.B pmlogreduce +are as follows: +.PP +.TP 7 +.BI \-A " align" +Specify a ``natural'' alignment of the output sample times; refer +to +.BR PCPIntro (1). +.PP +.TP 7 +.BI \-S " starttime" +Define the start of a time window to restrict the samples retrieved +from the +.I input +archive; refer to +.BR PCPIntro (1). +.PP +.TP 7 +.BI \-s " samples" +The argument +.I samples +defines the number of samples to be written to +.IR output . +If +.I samples +is 0 or +.B -s +is not specified, +.B pmlogreduce +will sample until the end of the PCP archive, +or the end of the time window as specified by +.BR -T , +whichever comes first. The +.B -s +option will override the +.B -T +option if it occurs sooner. +.PP +.TP 7 +.BI \-T " endtime" +Define the termination of a time window to restrict the samples +retrieved from the +.I input +archive; refer to +.BR PCPIntro (1). +.PP +.TP 7 +.BI \-v " volsamples" +The +.I output +archive is potentially a multi-volume data set, and the +.B \-v +option causes +.B pmlogreduce +to start a new volume after +.I volsamples +log records have been written to the +.I output +archive. +.RS 7 +.PP +Independent of any +.B \-v +option, each volume of an archive is limited to no more than +2^31 bytes, so +.I pmlogreduce +will automatically create a new volume for the archive before +this limit is reached. +.RE +.PP +.TP 7 +.BI \-t " interval" +Consecutive samples in the +.I output +archive will appear with a time delta defined by +.IR interval ; +refer to +.BR PCPIntro (1). +Note the default value is 600 (seconds, i.e. 10 minutes). +.PP +.TP 7 +.BI \-Z " timezone" +Use +.I timezone +when displaying the date and time, or interpreting the +.B \-S +and +.B \-T +options. +.I Timezone +is in the format of the environment variable +.B TZ +as described in +.BR environ (5). +.PP +.TP 7 +.B \-z +Use the local timezone of the host from the +.I input +archive when displaying the date and time, or interpreting the +.B \-S +and +.B \-T +options. +The default is to initially use the timezone of the local host. +.SH DATA REDUCTION +.PP +The statistical and temporal reduction follows the following rules: +.TP 4m +1. +Consecutive records from +.I input +are read without interpolation, and at most one output record +is written for each +.IR interval , +summarizing the performance data over that period. +.TP 4m +2. +If the semantics of a metric indicates it is +.B instantaneous +or +.B discrete +then +.I output +value is computed as the arithmetic mean of the observations (if any) +over each +.IR interval . +.TP 4m +3. +If the semantics of a metric indicates it is a +.B counter +then the following transformations are applied: +.RS +4m +.nr PD 0 +.TP 4m +a) +Metrics with 32-bit precision are promoted to 64-bit precision. +.TP 4m +b) +Any counter wrap (overflow) is noted, and appropriate adjustment made +in the value of the metric over each +.IR interval . +This will be correct in the case of a single counter wrap, but will +silently +.B underestimate +in the case where more than one counter wrap occurs between consecutive +observations in the +.I input +archive, and silently +.B overestimate +in the case where a counter is reset occurs between consecutive +observations in the +.I input +archive; unfortunately these situations cannot be detected, but +are believed to be rare events for the sort of production monitoring +environments where +.B pmlogreduce +is most likely to be deployed. +.RE +.PD +.TP 4m +4. +Any changes in instance domains, and indeed all metadata, is preserved. +.TP 4m +5. +Any ``mark'' records in the +.I input +archive (as created by +.BR pmlogextract (1)) +will be preserved in the +.I output +archive, so periods where no data is available are maintained, and data +interpolation will +.B not +occur across these periods when the +.I output +archive is subsequently processed with PCP applications. +.SH FILES +.PD 0 +For each of the +.I input +and +.I output +archives, several physical files are used. +.TP 10 +\f2archive\f3.meta +metadata (metric descriptions, instance domains, etc.) for the archive log +.TP +\f2archive\f3.0 +initial volume of metrics values (subsequent volumes have suffixes +.BR 1 , +.BR 2 , +\&...) \- for +.I input +these files may have been previously compressed with +.BR bzip2 (1) +or +.BR gzip (1) +and thus may have an additional +.B .bz2 +or +.B .gz +suffix. +.TP +\f2archive\f3.index +temporal index to support rapid random access to the other files in the +archive log. +.PD +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.I /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). +.SH SEE ALSO +.BR PCPIntro (1), +.BR pmdumplog (1), +.BR pmlc (1), +.BR pmlogextract (1), +.BR pmlogger (1), +.BR pcp.conf (5) +and +.BR pcp.env (5). +.SH DIAGNOSTICS +All error conditions detected by +.B pmlogreduce +are reported on +.I stderr +with textual (if sometimes terse) explanation. +.PP +Should the +.I input +archive be corrupted (this can happen +if the +.B pmlogger +instance writing the archive suddenly dies), then +.B pmlogreduce +will detect and report the position of the corruption in the file, +and any subsequent information from the +.I input +archive will not be processed. +.PP +If any error is detected, +.B pmlogreduce +will exit with a non-zero status. +.SH CAVEATS +.PP +The preamble metrics (pmcd.pmlogger.archive, pmcd.pmlogger.host, +and pmcd.pmlogger.port), which are automatically recorded by +.B pmlogger +at the start of the archive, may not be present in the archive output by +.BR pmlogreduce . +These metrics are only relevant while the archive is being created, +and have no significance once recording has finished. diff --git a/man/man1/pmlogrewrite.1 b/man/man1/pmlogrewrite.1 new file mode 100644 index 0000000..8808b42 --- /dev/null +++ b/man/man1/pmlogrewrite.1 @@ -0,0 +1,1002 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2011 Ken McDonell. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMLOGREWRITE 1 "" "Performance Co-Pilot" +.SH NAME +\f3pmlogrewrite\f1 \- rewrite Performance Co-Pilot archives +.SH SYNOPSIS +\f3$PCP_BINADM_DIR/pmlogrewrite\f1 +[\f3\-Cdiqsvw \f1] +[\f3\-c\f1 \f2config\f1] +\f2inlog\f1 [\f2outlog\f1] +.SH DESCRIPTION +.de KW +\\f(BI\\$1\\fP\\$2 +.. +.B pmlogrewrite +reads a Performance Co-Pilot (PCP) archive log +identified by +.I inlog +and creates a PCP archive log in +.IR outlog . +Under normal usage, the +.B \-c +option will be used to nominate a configuration file or files +that contains specifications (see the +.B "REWRITING RULES SYNTAX" +section below) +that describe how the data and metadata from +.I inlog +should be transformed to produce +.IR outlog . +.PP +The typical uses for +.B pmlogrewrite +would be to accommodate the evolution of Performance Metric Domain Agents +(PMDAs) where the names, metadata and semantics of metrics and their associated +instance domains may change over time, e.g. promoting the type of a metric +from a 32-bit to a 64-bit integer, or renaming a group of metrics. +Refer to the +.B EXAMPLES +section for some additional use cases. +.PP +.B pmlogrewrite +is most useful where PMDA changes, or errors in the production environment, +result in archives that cannot be combined with +.BR pmlogextract (1). +By pre-processing the archives with +.B pmlogrewrite +the resulting archives may be able to be merged with +.BR pmlogextract (1). +.PP +The input +.I inlog +must be a PCP archive log +created by +.BR pmlogger (1), +or possibly one of the tools that read and create PCP archives, e.g. +.BR pmlogextract (1) +and +.BR pmlogreduce (1). +.PP +If no +.B \-c +option is specified, then the default behavior simply creates +.I outlog +as a copy of +.IR inlog . +This is a little more complicated than +.BR cat (1), +as each PCP archive is made up of several physical files. +.PP +While +.B pmlogrewrite +may be used to repair some data consistency issues in PCP archives, +there is also a class of repair tasks that cannot be handled by +.B pmlogrewrite +and +.BR pmloglabel (1) +may be a useful tool in these cases. +.SH COMMAND LINE OPTIONS +The command line options for +.B pmlogrewrite +are as follows: +.TP 7 +.B \-C +Parse the rewriting rules and quit. +.I outlog +is not created. +When +.B \-C +is specified, this also sets +.B \-v +and +.B \-w +so that all warnings and verbose messages are displayed as +.I config +is parsed. +.TP 7 +.BI \-c " config" +If +.I config +is a file or symbolic link, +read and parse rewriting rules from there. +If +.I config +is a directory, then all of the files or symbolic links in that +directory (excluding those beginning with a period ``.'') will +be used to provide the rewriting rules. +Multiple +.B \-c +options are allowed. +.TP 7 +.B \-d +Desperate mode. Normally if a fatal error occurs, all trace of +the partially written PCP archive +.I outlog +is removed. With the +.B \-d +option, the partially created +.I outlog +archive log is not removed. +.TP 7 +.B \-i +Rather than creating +.IR outlog , +.I inlog +is rewritten in place when the +.B \-i +option is used. +A new archive is created using temporary file names and then renamed to +.I inlog +in such a way that +if any errors (not warnings) are encountered, +.I inlog +remains unaltered. +.TP 7 +.B \-q +Quick mode, where if there are no rewriting actions to be +performed (none of the global data, instance domains or metrics +from +.I inlog +will be changed), then +.B pmlogrewrite +will exit (with status 0, so success) immediately after parsing +the configuration file(s) and +.I outlog +is not created. +.TP 7 +.B \-s +When the ``units'' of a metric are changed, if the dimension in terms +of space, time and count is unaltered, then the scaling factor is being changed, +e.g. BYTE to KBYTE, or MSEC\u\s-3-1\s0\d to USEC\u\s-3-1\s0\d, or the +composite MBYTE.SEC\u\s-3-1\s0\d to KBYTE.USEC\u\s-3-1\s0\d. +The +motivation may be (a) that the original metadata was wrong but the +values in +.I inlog +are correct, or (b) the metadata is changing so the values need +to change as well. The default +.B pmlogrewrite +behaviour matches case (a). If case (b) applies, then use the +.B \-s +option and the values of all the +metrics with a scale factor change in each result will be rescaled. +For finer control over value rescaling refer to +the +.KW RESCALE +option for the +.KW UNITS +clause of the metric rewriting rule described below. +.TP 7 +.BI \-v +Increase verbosity of diagnostic output. +.TP 7 +.BI \-w +Emit warnings. Normally +.B pmlogrewrite +remains silent for any warning that is not fatal and +it is expected that for a particular archive, some (or indeed, all) +of the rewriting specifications may not apply. For example, changes to +a PMDA may be captured in a set of rewriting rules, but a single archive +may not contain all of the modified metrics nor all of the modified +instance domains and/or instances. Because these cases are expected, +they do not prevent +.B pmlogrewrite +executing, and rules that do not apply to +.I inlog +are silently ignored by default. +Similarly, some rewriting rules may involve no change because +the metadata in +.I inlog +already matches the intent of the rewriting rule to correct data +from a previous version of a PMDA. +The +.B \-w +flag forces warnings to be emitted for all of these cases. +.PP +The argument +.I outlog +is required in all cases, except when +.B \-i +is specified. +.SH REWRITING RULES SYNTAX +A configuration file +contains zero or more rewriting rules as defined below. +.PP +Keywords and special punctuation characters are shown below in +.KW bolditalic +font and are case-insensitive, so +.KW METRIC , +.KW metric +and +.KW Metric +are all equivalent in rewriting rules. +.PP +The character ``#'' introduces +a comment and the remainder of the line is ignored. Otherwise the +input is relatively free format with optional white space (spaces, tabs or +newlines) between lexical items in the rules. +.PP +A +.B global +rewriting rule has the form: +.PP +.KW GLOBAL +.KW { +.I globalspec +\&... +.KW } +.PP +where +.I globalspec +is zero or more of the following clauses: +.RS +4n +.PP +.KW HOSTNAME +.KW -> +.I hostname +.RS +4n +.PP +Modifies the label records in the +.I outlog +PCP archive, so that the metrics will appear to have +been collected from the host +.IR hostname . +.RE +.PP +.KW TIME +.KW -> +.I delta +.RS +4n +.PP +Both metric values and the instance domain metadata in a PCP +archive carry timestamps. +This clause forces all the timestamps to be adjusted by +.IR delta , +where +.I delta +is an optional sign ``+'' (the default) or ``\-'', an optional number of +hours followed by a colon ``:'', an optional number of minutes followed by a +colon ``:'', a number of seconds, an optional fraction of seconds following +a period ``.''. The simplest example would be ``30'' to increase the +timestamps by 30 seconds. A more complex example would be ``\-23:59:59.999'' +to move the timestamps backwards by one millisecond less than one day. +.RE +.PP +.KW TZ +.KW -> +\f(BI"\fP\fItimezone\fP\f(BI"\fP +.RS +4n +.PP +Modifies the label records in the +.I outlog +PCP archive, so that the metrics will appear to have been +collected from a host with a local timezone of +.IR timezone . +.I timezone +must be enclosed in quotes, and should conform to the valid +timezone syntax rules for the local platform. +.RE +.RE +.PP +An +.B indom +rewriting rule modifies an instance domain and has the form: +.PP +.KW INDOM +\fIdomain\fP\f(BI.\fP\fIserial\fP +.KW { +.I indomspec +\&... +.KW } +.PP +where +.I domain +and +.I serial +identify one or more existing instance domains from +.I inlog +\- typically +.I domain +would be an integer in the range 1 to 510 +and +.I serial +would be an integer in the range 0 to 4194304. +.PP +As a special +case +.I serial +could be an asterisk ``*'' which means the rule applies to every +instance domain with a domain number of +.IR domain . +.PP +If a designated instance domain is not in +.I inlog +the rule has no effect. +.PP +The +.I indomspec +is zero or more of the following clauses: +.RS +4n +.PP +.KW INAME +"\fIoldname\fP" +.KW -> +"\fInewname\fP" +.RS +4n +.PP +The instance identified by the external instance name +.I oldname +is renamed to +.IR newname . +Both +.I oldname +and +.I newname +must be enclosed in quotes. +.PP +As a special case, the new name may be the keyword +.KW DELETE +(with no quotes), and then the instance +.I oldname +will be expunged from +.I outlog +which removes it from the instance domain metadata and removes all +values of this instance for all the associated metrics. +.PP +If the instance names contain any embedded +spaces then special care needs to be taken in respect of the +PCP instance naming rule that treats the leading non-space +part of the instance name as the unique portion of the name for +the purposes of matching and ensuring uniqueness within an +instance domain, refer to +.BR pmdaInstance (3) +for a discussion of this issue. +.PP +As an illustration, consider the hypothetical instance domain for a metric +which contains 2 instances with the following names: +.RS +4 +.ft CW +.nf +red +eek urk +.fi +.ft P +.RE +.PP +Then some possible +.KW INAME +clauses might be: +.TP +10n +\f(CW"eek" -> "yellow like a flower"\fP +Acceptable, +.I oldname +"eek" matches the "eek urk" instance. +.TP +10n +\f(CW"red" -> "eek"\fP +Error, +.I newname +"eek" matches the existing "eek urk" +instance. +.TP +10n +\f(CW"eek urk" -> "red of another hue"\fP +Error, +.I newname +"red of another hue" matches the existing "red" +instance. +.RE +.PP +.KW INDOM +.KW -> +\fInewdomain\fP\f(BI.\fP\fInewserial\fP +.RS +4n +.PP +Modifies the metadata for the instance domain and every metric associated +with the instance domain. +As a special case, +.I newserial +could be an asterisk ``*'' which means use +.I serial +from the +.B indom +rewriting rule, although this is most useful when +.I serial +is also an asterisk. +So for example: +.RS +4n +.ft CW +indom 29.* { indom -> 109.* } +.ft P +.RE +will move all instance domains from domain 29 to domain 109. +.RE +.PP +.KW INDOM +.KW -> +.KW DUPLICATE +\fInewdomain\fP\f(BI.\fP\fInewserial\fP +.RS +4n +.PP +A special case of the previous +.KW INDOM +clause where the instance domain is a duplicate copy of the +\fIdomain\fP\f(BI.\fP\fIserial\fP instance domain from the +.I indom +rewriting rule, and then any +mapping rules are applied to the copied +\fInewdomain\fP\f(BI.\fP\fInewserial\fP instance domain. This is +useful when a PMDA is split and the same instance domain needs to +be replicated for domain \fIdomain\fP and domain \fInewdomain\fP. +So for example if the metrics +.I foo.one +and +.I foo.two +are both defined over instance domain 12.34, and +.I foo.two +is moved to another PMDA using domain 27, then the +following rewriting rules could be used: +.RS +4n +.ft CW +indom 12.34 { indom -> duplicate 27.34 } +.br +metric foo.two { indom -> 27.34 pmid -> 27.*.* } +.ft P +.RE +.RE +.PP +.KW INST +\fIoldid\fP +.KW -> +\fInewid\fP +.RS +4n +.PP +The instance identified by the internal instance identifier +.I oldid +is renumbered to +.IR newid . +Both +.I oldid +and +.I newid +are integers in the range 0 to 2\u\s-331\s0\d-1. +.PP +As a special case, +.I newid +may be the keyword +.KW DELETE +and then the instance +.I oldid +will be expunged from +.I outlog +which removes it from the instance domain metadata and removes all +values of this instance for all the associated metrics. +.RE +.RE +.PP +A +.B metric +rewriting rule has the form: +.PP +.KW METRIC +.I metricid +.KW { +.I metricspec +\&... +.KW } +.PP +where +.I metricid +identifies one or more existing metrics from +.I inlog +using either a metric name, or the internal encoding for a metric's PMID as +\fIdomain\fP\f(BI.\fP\fIcluster\fP\f(BI.\fP\fIitem\fP. +In the latter case, typically +.I domain +would be an integer in the range 1 to 510, +.I cluster +would be an integer in the range 0 to 4095, +and +.I item +would be an integer in the range 0 to 1023. +.PP +As special +cases +.I item +could be an asterisk ``*'' which means the rule applies to every +metric with a domain number of +.I domain +and a cluster number of +.IR cluster , +or +.I cluster +could be an asterisk which means the rule applies to every +metric with a domain number of +.I domain +and an item number of +.IR item , +or both +.I cluster +and +.I item +could be asterisks, and rule applies to every metric with a domain +number of +.IR domain . +.PP +If a designated metric is not in +.I inlog +the rule has no effect. +.PP +The +.I metricspec +is zero or more of the following clauses: +.RS +4n + +.PP +.KW DELETE +.RS +4n +.PP +The metric is completely removed from +.IR outlog , +both the metadata and all values in results are expunged. +.RE + +.PP +.KW INDOM +.KW -> +\fInewdomain\fP\f(BI.\fP\fInewserial\fP [ +.I pick +] +.RS +4n +.PP +Modifies the metadata to change the instance domain for this metric. +The new instance domain must exist in +.IR outlog . +.PP +The optional +.I pick +clause may be used to select one input value, or compute an aggregate +value from the instances in an input result, or assign an internal +instance identifier to a single output value. +If no +.I pick +clause is specified, the default behaviour is to copy all input values +from each input result to +an output result, however if the input instance domain is singular +(indom +.BR PM_INDOM_NULL ) +then the one output value must be assigned an internal instance +identifier, which is 0 by default, unless over-ridden by a +.KW INST +or +.KW INAME +clause as defined below. +.PP +The choices for +.I pick +are as follows: +.TP +12n +\f(BIOUTPUT FIRST\fP +choose the value of the first instance from each input result +.TP +12n +\f(BIOUTPUT LAST\fP +choose the value of the last instance from each input result +.TP +12n +\f(BIOUTPUT INST\fP \fIinstid\fP +choose the value of the instance with internal instance identifier +.I instid +from each result; the sequence of rewriting rules ensures the +.KW OUTPUT +processing happens before instance identifier renumbering +from any associated +.B indom +rule, so +.I instid +should be one of the internal instance identifiers that appears in +.I inlog +.TP +12n +\f(BIOUTPUT INAME\fP "\fIname\fP" +choose the value of the instance with +.I name +for its external instance name +from each result; the sequence of rewriting rules ensures the +.KW OUTPUT +processing happens before instance renaming +from any associated +.B indom +rule, so +.I name +should be one of the external instance names that appears in +.I inlog +.TP +12n +\f(BIOUTPUT MIN\fP +choose the smallest value in each result (metric type must be numeric +and output instance will be 0 for a non-singular instance domain) +.TP +12n +\f(BIOUTPUT MAX\fP +choose the largest value in each result (metric type must be numeric +and output instance will be 0 for a non-singular instance domain) +.TP +12n +\f(BIOUTPUT SUM\fP +choose the sum of all values in each result (metric type must be numeric +and output instance will be 0 for a non-singular instance domain) +.TP +12n +\f(BIOUTPUT AVG\fP +choose the average of all values in each result (metric type must be numeric +and output instance will be 0 for a non-singular instance domain) +.PP +If the input instance domain is singular +(indom +.BR PM_INDOM_NULL ) +then independent of any +.I pick +specifications, there is at most one value in each input result and +so +.KW FIRST , +.KW LAST , +.KW MIN , +.KW MAX , +.KW SUM +and +.KW AVG +are all equivalent and the output instance identifier will be 0. +.PP +In general it is an error to specify a rewriting action for the +same metadata or result values more than once, e.g. more than one +.KW INDOM +clause for the same instance domain. The one exception is the possible +interaction between the +.KW INDOM +clauses in the +.B indom +and +.B metric +rules. +For example the metric +.I sample.bin +is defined over the instance domain 29.2 in +.I inlog +and the following is acceptable (albeit redundant): +.RS +4n +.ft CW +.nf +indom 29.* { indom -> 109.* } +metric sample.bin { indom -> 109.2 } +.fi +.ft P +.RE +However the following is an error, because the instance domain for +.I sample.bin +has two conflicting definitions: +.RS +4n +.ft CW +.nf +indom 29.* { indom -> 109.* } +metric sample.bin { indom -> 123.2 } +.fi +.ft P +.RE +.RE + +.PP +.KW INDOM +.KW -> +.KW NULL [ +.I pick +] +.RS +4n +.PP +The metric (which must have been +previously defined over an instance domain) is being modified to +be a singular metric. This involves a metadata change and collapsing +all results for this metric so that multiple values become one value. +.PP +The optional +.I pick +part of the clause defines how the one value for each result +should be calculated and follows the same rules as described for the +non-NULL +.KW INDOM +case above. +.PP +In the absence of +.IR pick , +the default is +.KW "OUTPUT FIRST" . +.RE + +.PP +.KW NAME +.KW -> +.I newname +.RS +4n +.PP +Renames the metric in the PCP archive's metadata that supports +the Performance Metrics Name Space (PMNS). +.I newname +should not match any existing name in the archive's PMNS and must +follow the syntactic rules for valid metric names as outlined in +.BR pmns (5). +.RE + +.PP +.KW PMID +.KW -> +\fInewdomain\fP\f(BI.\fP\fInewcluster\fP\f(BI.\fP\fInewitem\fP +.RS +4n +.PP +Modifies the metadata and results to renumber the metric's PMID. +As special cases, +.I newcluster +could be an asterisk ``*'' which means use +.I cluster +from the +.B metric +rewriting rule and/or +.I item +could be an asterisk which means use +.I item +from the +.B metric +rewriting rule. +This is most useful when +.I cluster +and/or +.I item +is also an asterisk. +So for example: +.RS +4n +.ft CW +metric 30.*.* { pmid -> 123.*.* } +.ft P +.RE +will move all metrics from domain 30 to domain 123. +.RE + +.PP +.KW SEM +.KW -> +.I newsem +.RS +4n +.PP +Change the semantics of the metric. +.I newsem +should be the XXX part of the name of one of the +.B PM_SEM_XXX +macros defined in <pcp/pmapi.h> or +.BR pmLookupDesc (3), +e.g. +.KW COUNTER +for +.BR PM_TYPE_COUNTER . +.PP +No data value rewriting is performed as a result of the +.KW SEM +clause, so the usefulness +is limited to cases where a version of the associated +PMDA was exporting incorrect semantics for the metric. +.BR pmlogreduce (1) +may provide an alternative in cases where re-computation of result +values is desired. +.RE + +.PP +.KW TYPE +.KW -> +.I newtype +.RS +4n +.PP +Change the type of the metric which alters the metadata and may change the +encoding of values in results. +.I newtype +should be the XXX part of the name of one of the +.B PM_TYPE_XXX +macros defined in <pcp/pmapi.h> or +.BR pmLookupDesc (3), +e.g. +.KW FLOAT +for +.BR PM_TYPE_FLOAT . +.PP +Type conversion is only supported for cases where the old and new +metric type is numeric, so +.BR PM_TYPE_STRING , +.B PM_TYPE_AGGREGATE +and +.B PM_TYPE_EVENT +are not allowed. +Even for the numeric cases, some conversions may produce run-time errors, +e.g. integer overflow, or attempting to rewrite a negative value into +an unsigned type. +.RE + +.PP +.KW UNITS +.KW -> +.I newunits +[ +.KW RESCALE +] +.RS +4n +.PP +.I newunits +is six values separated by commas. The first 3 values describe the +dimension of the metric along the dimensions of space, time and count; these +are integer values, usually 0, 1 or \-1. The remaining 3 values describe +the scale of the metric's values in the dimensions of space, time and +count. +Space scale values should be 0 (if the space dimension is 0), else +the XXX part of the name of one of the +.B PM_SPACE_XXX +macros, e.g. +.KW KBYTE +for +.BR PM_TYPE_KBYTE . +Time scale values should be 0 (if the time dimension is 0), else +the XXX part of the name of one of the +.B PM_TIME_XXX +macros, e.g. +.KW SEC +for +.BR PM_TIME_SEC . +Count scale values should be 0 (if the time dimension is 0), else +.KW ONE +for +.BR PM_COUNT_ONE . +.PP +The +.BR PM_SPACE_XXX , +.B PM_TIME_XXX +and +.B PM_COUNT_XXX +macros are defined in <pcp/pmapi.h> or +.BR pmLookupDesc (3). +.PP +When the scale is changed (but the dimension is +unaltered) the optional keyword +.KW RESCALE +may be used to chose value rescaling as per the +.B \-s +command line option, but applied to just this metric. +.RE + +.PP +When changing the domain number for a metric or instance domain, +the new domain number will usually match an existing PMDA's domain +number. If this is not the case, then the new domain number +should not be randomly chosen; consult +.B $PCP_VAR_DIR/pmns/stdpmid +for domain numbers that are already assigned to PMDAs. +.SH EXAMPLES +.PP +To promote the values of the per-disk IOPS metrics to 64-bit to +allow aggregation over a long time period for capacity +planning, or because the PMDA has changed to export 64-bit counters +and we want to convert old archives so they can be processed +alongside new archives. +.RS +4 +.ft CW +.nf +metric disk.dev.read { type -> U64 } +metric disk.dev.write { type -> U64 } +metric disk.dev.total { type -> U64 } +.fi +.ft P +.RE +.PP +The instances associated with the load average metric +.B kernel.all.load +could be renamed and renumbered by the +rules below. +.RS +4 +.ft CW +.nf +# for the Linux PMDA, the kernel.all.load metric is defined +# over instance domain 60.2 +indom 60.2 { + inst 1 -> 60 iname "1 minute" -> "60 second" + inst 5 -> 300 iname "5 minute" -> "300 second" + inst 15 -> 900 iname "15 minute" -> "900 second" +} +.fi +.ft P +.RE +.PP +If we decide to split the ``proc'' metrics out of the Linux PMDA, this +will involve changing the domain number for the PMID of these metrics +and the associated instance domains. The rules below would rewrite an +old archive to match the changes after the PMDA split. +.RS +4 +.ft CW +.nf +# all Linux proc metrics are in 7 clusters +metric 60.8.* { pmid -> 123.*.* } +metric 60.9.* { pmid -> 123.*.* } +metric 60.13.* { pmid -> 123.*.* } +metric 60.24.* { pmid -> 123.*.* } +metric 60.31.* { pmid -> 123.*.* } +metric 60.32.* { pmid -> 123.*.* } +metric 60.51.* { pmid -> 123.*.* } +# only one instance domain for Linux proc metrics +indom 60.9 { indom -> 123.0 } +.fi +.ft P +.RE +.SH FILES +.PD 0 +For each of the +.I inlog +and +.I outlog +archive logs, several physical files are used. +.TP 10 +\f2archive\f3.meta +metadata (metric descriptions, instance domains, etc.) for the archive log +.TP +\f2archive\f3.0 +initial volume of metrics values (subsequent volumes have suffixes +.BR 1 , +.BR 2 , +\&...). +.TP +\f2archive\f3.index +temporal index to support rapid random access to the other files in the +archive log. +.PD +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.I /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). +.SH SEE ALSO +.BR PCPIntro (1), +.BR pmdaInstance (3), +.BR pmdumplog (1), +.BR pmlogger (1), +.BR pmlogextract (1), +.BR pmloglabel (1), +.BR pmlogreduce (1), +.BR pmLookupDesc (3), +.BR pmns (5), +.BR pcp.conf (5) +and +.BR pcp.env (5). +.SH DIAGNOSTICS +All error conditions detected by +.B pmlogrewrite +are reported on +.I stderr +with textual (if sometimes terse) explanation. +.PP +Should the input archive log be corrupted (this can happen +if the +.B pmlogger +instance writing the log suddenly dies), then +.B pmlogrewrite +will detect and report the position of the corruption in the file, +and any subsequent information from that archive log will not be processed. +.PP +If any error is detected, +.B pmlogrewrite +will exit with a non-zero status. diff --git a/man/man1/pmlogsummary.1 b/man/man1/pmlogsummary.1 new file mode 100644 index 0000000..ee159d0 --- /dev/null +++ b/man/man1/pmlogsummary.1 @@ -0,0 +1,339 @@ +'\"! tbl | mmdoc +'\"macro stdmacro +.\" +.\" Copyright (c) 2000 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMLOGSUMMARY 1 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmlogsummary\f1 \- calculate averages of metrics stored in a PCP archive +.SH SYNOPSIS +\f3pmlogsummary\f1 +[\f3\-abfFHiIlmMNsvxyz\f1] +[\f3\-B\f1 \f2nbins\f1] +[\f3\-n\f1 \f2pmnsfile\f1] +[\f3\-p\f1 \f2precision\f1] +[\f3\-S\f1 \f2starttime\f1] +[\f3\-T\f1 \f2endtime\f1] +[\f3\-Z\f1 \f2timezone\f1] +\f2archive\f1 +[\f2metricname\f1 ...] +.SH DESCRIPTION +.B pmlogsummary +prints statistical information about metrics of numeric type contained within +the files of a Performance Co-Pilot (PCP) archive log. The default output prints +time averages for both counter and non-counter metrics. +The archive log has the base name +.IR archive , +typically created using +.BR pmlogger (1). +.PP +The metrics of interest are named in the +.I metricname +arguments. +If +.I metricname +is a non-leaf node in the Performance Metrics Name Space (\c +.BR pmns (5)), +then +.B pmlogsummary +will recursively descend the PMNS and report on all leaf nodes. +If no +.I metricname +argument is given, the root of the namespace is used. +.PP +Normally +.B pmlogsummary +operates on the default +.BR pmns (5), +however if the +.B \-n +option is specified an alternative namespace is loaded +from the file +.IR pmnsfile . +.PP +The command line options +.B \-S +and +.B \-T +can be used to specify a time window over which metrics should be summarized. +These options are common to most Performance Co-Pilot tools and are fully +described in +.BR PCPIntro (1). +.PP +The remaining options control the specific information to be reported. +Metrics with counter semantics are converted to rates before being +evaluated. +.TP +.B \-a +Print all information. This is equivalent to +.BR \-blmMy . +.TP +.B \-b +Print both forms of averaging, that is both stochastic and time averaging. +.TP +.B \-B +Print the approximate distribution of values, using histogram bins such +that the value range (minimum - maximum) for each metric is divided +equally into +.I nbins +bins, and each bin accumulates the frequency of observed values in the +corresponding range. +Refer to the ``OUTPUT FORMAT'' section below for a description of how the +distribution of values is reported). +.TP +.B \-f +Spreadsheet format \- the tab character is used to delimit each field +printed. This option is intended to allow +.B pmlogsummary +output to be imported directly into common spreadsheet applications. +.TP +.B \-F +Spreadsheet format \- the comma character is used to delimit each field +printed. This option is intended to allow +.B pmlogsummary +output to be imported directly into common spreadsheet applications which +support the Comma Separated Value (.csv) format. +.TP +.B \-H +Print a one-line header at the start showing what each field represents. +.TP +.B \-l +Also print the archive label, showing the log format version, +the time and date for the start and end of the archive time window, +and the host from which the performance metrics values were collected. +.TP +.B \-i +Also print the time at which the minimum value was logged. The format of this +timestamp is described in the ``OUTPUT FORMAT'' section below. +.TP +.B \-I +Also print the time at which the maximum value was logged. The format of this +timestamp is described in the ``OUTPUT FORMAT'' section below. +.TP +.B \-m +Also print the minimum logged value for each metric. +.TP +.B \-M +Also print the maximum logged value for each metric. +.TP +.B \-s +Print (only) the sum of all logged values for each metric. +.TP +.B \-N +Suppress any warnings resulting from individual archive fetches (default). +.TP +.B \-p +Print all floating point numbers with +.I precision +digits after the decimal place. +.TP +.B \-v +Report (verbosely) on warnings resulting from individual archive fetches. +.TP +.B \-x +Print stochastic averages instead of the default (time averages). +.TP +.B \-y +Also print the number of samples encountered in the archive for each metric. +.PP +By default, +.B pmlogsummary +reports the time of day according to the local timezone on the +system where +.B pmlogsummary +is run. +The +.B \-Z +option changes the timezone to +.I timezone +in the format of the environment variable +.B TZ +as described in +.BR environ (5). +The +.B \-z +option changes the timezone to the local timezone at the +host that is the source of the performance metrics, as specified in +the label record of the archive log. +.SH OUTPUT FORMAT +The +.B pmlogsummary +output format is spartan as it is intended to be post-processed with +standard tools. This means that there is no annotation associated with each +output field which would make processing harder. The intention is that +.B pmlogsummary +output be massaged into a format which can be used by a spreadsheet program, +is suitable for inclusion in a web page, or whatever. +.PP +For each metric, +.B pmlogsummary +produces a single output line as follows: +.PP +.in 1.0i +.ft CW +.nf +\f2metricname\f1 \f2value(s)\f1 \f2units\f1 +.fi +.ft R +.in +.PP +For metrics with multiple instances, +.B pmlogsummary +produces multiple lines of output as follows: +.PP +.in 1.0i +.ft CW +.nf +\f2metricname\f1 ["\f2instance 1\f1"] \f2value(s)\f1 \f2units\f1 +\f2metricname\f1 ["\f2instance 2\f1"] \f2value(s)\f1 \f2units\f1 +\f2metricname\f1 ["\f2instance N\f1"] \f2value(s)\f1 \f2units\f1 +.fi +.ft R +.in +.PP +The printed \f2value(s)\f1 for each metric always follow this order: +stochastic average, time average, minimum, minimum timestamp, maximum, +maximum timestamp, count, [bin 1 range], bin 1 count, ... [bin +.I nbins +range], bin +.I nbins +count. +The individual values for each metric are space-separated (unless the +.B \-f +option is used). +.PP +All counter metrics which are measured in units of time will be converted +to seconds before being rate converted and used in the +.B pmlogsummary +calculations. The values calculated for these metrics are also printed +in seconds. +.PP +The units will be displayed in the format described by +.BR pmUnitsStr (3). +.PP +Given either of the +.B -i +or +.B -I +options, +.B pmlogsummary +produces two different timestamp formats, depending on the +interval over which it is run. +For an interval greater than 24 hours, the date is displayed in addition +to the time at which the maxima and/or minima occurred. +If the extent of the data being checked is less than 24 hours, +a more precise format is used (time is displayed with millisecond +precision, but without the date). +.PP +.SH NOTES +The average for an individual metric is calculated as follows: +.PP +Non-counter metrics are averaged using stochastic averaging - +each observation has an equal weighting towards +the calculation of the average (the sum of all values divided +by the total number of values, for each metric). +.PP +Counter metrics are averaged using time averaging (by default), +but the +.B \-x +option can be used to specify that counters be averaged using +the stochastic method instead. When calculating a time average, +the sum of the product of each sample value multiplied by the time difference +between each sample, is divided by the total time over which +that metric was logged. +.PP +Counter metrics whose measurements do not span 90% of the archive will be +printed with the metric name prefixed by an asterisk (*). +.PP +.SH EXAMPLE +.sp +.nf +$ pmlogsummary \-aN \-p 1 \-B 3 surf network.interface.out.bytes +Log Label (Log Format Version 1) +Performance metrics from host www.sgi.com + commencing Tue Jan 14 20:50:50.317 1997 + ending Wed Jan 29 10:13:07.387 1997 +network.interface.out.bytes ["xpi0"] 202831.3 202062.5 20618.7 \e + 1235067.7 971 [<=425435.0] 912 [<=830251.4] 42 [<=1235067.7] \e + 17 byte / sec +network.interface.out.bytes ["xpi1"] 0.0 0.0 0.0 0.0 1033 [<=0.0] \e + 1033 [] 0 [] 0 byte / sec +network.interface.out.bytes ["et0"] 0.0 0.0 0.0 0.0 1033 [<=0.0] \e + 1033 [] 0 [] 0 byte / sec +network.interface.out.bytes ["lo0"] 899.0 895.2 142.6 9583.1 1031 \e + [<=3289.4] 1027 [<=6436.2] 3 [<=9583.1] 1 byte / sec +.fi +.sp +A description of each field in the first line of statistical output, which +describes one instance of the network.interface.out.bytes metric, +follows: +.TS +box,center; +cf(R) | cf(R) +lf(CW) | lf(R). +Field Meaning +_ +["xpi0"] instance name +202831.3 stochastic average +202062.5 time average +20618.7 minimum value +1235067.7 maximum value +971 total number of values for this instance +[<=425435.0] range for first bin (20618.7-425435.0) +912 number of values in first bin +[<=830251.4] range for second bin (425435.0-830251.4) +42 number of values in second bin +[<=1235067.7] range for third bin (830251.4-1235067.7) +17 number of values in third bin +byte / sec base units for this metric +.TE +.SH FILES +.PD 0 +.TP 10 +.BI $PCP_VAR_DIR/pmns/ * +default PMNS specification files +.TP +.BI $PCP_LOG_DIR/pmlogger/ hostname +Default directory for PCP archives containing performance +metric values collected from the host +.IR hostname . +.PD +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.I /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). +.SH SEE ALSO +.BR PCPIntro (1), +.BR pmchart (1), +.BR pmdumptext (1), +.BR pmlogextract (1), +.BR pmlogger (1), +.BR pmval (1), +.BR PMAPI (3), +.BR pmUnitsStr (3) +and +.BR pmns (5). +.SH DIAGNOSTICS +All are generated on standard error and are intended to be self- +explanatory. diff --git a/man/man1/pmmgr.1 b/man/man1/pmmgr.1 new file mode 100644 index 0000000..2ae53e3 --- /dev/null +++ b/man/man1/pmmgr.1 @@ -0,0 +1,340 @@ +'\"! tbl | mmdoc +'\"macro stdmacro +.\" +.\" Copyright (c) 2013-2014 Red Hat, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMMGR 1 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmmgr\f1 \- pcp daemon manager +.SH SYNOPSIS +\f3pmmgr\f1 +[\f3\-v\f1] +[\f3\-c\f1 \f2config-directory\f1] +[\f3\-p\f1 \f2polling-interval\f1] +[\f3\-l\f1 \f2log-file\f1] + +.SH DESCRIPTION +.B pmmgr +manages a collection of PCP daemons for a set of discovered local and +remote hosts running the Performance Metrics Collection Daemon (PMCD), +according to zero or more configuration directories. It keeps a +matching set of +.BR pmlogger " and/or " pmie +daemons running, and their archives/logs merged/rotated. It supplants +the older +.BR pmlogger_* " and " pmie_* +check/daily management shell scripts. +.P +pmmgr is largely self-configuring and perseveres despite most run-time +errors. pmmgr runs in the foreground until interrupted. When signaled, +it will stop its running daemons before exiting. +.P +A description of the command line options specific to +.B pmmgr +follows: +.TP 5 +.B \-c +.I directory +adds a given configuration directory to pmmgr. pmmgr can supervise +multiple different configurations at the same time. Errors in the +configuration may be noted to standard error, but pmmgr will fill in +missing information with built-in defaults. The default directory is +.I $PCP_SYSCONF_DIR/pmmgr +.TP +.B \-p +.I polling-interval +sets the host-discovery polling interval to the given number of seconds. +The default is 60. Daemons for a particular target host will be restarted +no more frequently than this interval. +.TP +.B \-l +.I log-file +redirects standard output & error to the given log file, which is created anew +.TP +.B \-v +adds more verbose tracing to standard output. + +.SH CONFIGURATION +A +.B pmmgr +configuration identifies which hosts should be monitored, which +daemons should be maintained for them, and what options those daemons +should be run with. pmmgr uses a small number of files in a +configuration directory, instead of lines in a text file. The +individual files carry zero or more lines of 100% pure configuration +text, and no comments. (If desired, a configuration may be commented +upon with any other file, such as a free-form README.) + +.SS TARGET SELECTION + +This set of configuration files identifies where pmmgr should search +for pmcd instances, how to uniquely identify them, and where state +such as log files should be kept for each. Ideally, a persistent & +unique host-id string is computed for each potential target pmcd from +specified metric values. This host-id is also used as a subdirectory +name for locating daemon data. + +.TP +hostid\-metrics +This file contains one or more lines of metric specifications in the format +accepted by +.IR pmParseMetricSpec . +Metrics without instance specifiers mean all instances of that metric. +These are used to generate the +.IR unique +host-id string for each pmcd server that pmmgr discovers. Upon discovery, +all the metrics/instances named are queried, string values fetched, and +normalized/concatenated into a single hyphenated printable string. +The default is the single metric +.BR pmcd.hostname , +which is sufficient if all the hosts discovered have unique hostname(2). If +they don't, you should add other pcp metric specifications to set them apart +at your site. The more you add, the longer the host-id string, but the more +likely that accidental duplication is prevented. + +However, it may be desirable for a host-id to also be +.IR persistent , +so that if the target host goes offline and later returns, the new +host-id matches the previous one, because then old and new histories can be joined. +This argues against using metrics whose values vary from boot to boot. + +Some candidate metrics to consider: +.IR network.interface.hw_addr ", " network.interface.inet_addr["eth0"] ", " +.IR network.interface.ipv6_addr ", " kernel.uname.nodename +.\" some others would be nice to have: +.\" CPU serial numbers +.\" VM uuid +.\" DMI serial numbers + +.TP +log\-directory +This file contains the path of a directory beneath which the per-host-id +subdirectories are to be created by pmmgr. If it is not a full path, it +is implicitly relative to the configuration directory itself. The default is +.BR $PCP_LOG_DIR/pmmgr/ . + +.TP +target\-host +This file contains one or more lines containing pmcd host specifications, as +described on the +.IR PCPintro (1) +man page. Each poll interval, pmmgr will attempt to make a brief +.IR pmNewContext +connection to the host to check liveness. It is not a problem if more than +one specification for the same host is listed, because the host-id processing +eliminates duplicates, and chooses an arbitrary specification among them. +The default is to target pmcd at +.BR local: . + +.TP +target\-discovery +This file contains one or more lines containing specifications for the +.IR pmDiscoverServices +PMAPI call, each of which may map onto a fluctuating set of local or remote +pmcd servers. Each poll interval, pmmgr will attempt to rerun discovery with +all of the given specifications. Again it is not a problem if more than one +specification matches the same actual pmcd: one confirmed access path is +arbitrarily selected. The default is to do +.BR "no discovery" . +Consider including +.IR avahi,timeout=5 +to rely in pmcd self-announcements on the local network (searching for up to +five seconds each time). + +.TP +log\-subdirectory\-gc +This file may contain a time interval specification as per the +.IR PCPintro +man page. All subdirectories of the log\-directory are +presumed to contain data for pmmgr-monitored servers. Those that +have not been touched (in the +.BR stat/mtime +sense) in at least that long, and not associated with a currently +monitored target, are deleted entirely. This value should be +longer than the longest interval that pmmgr normally recreates +archives (such as due to pmmgr restarts, and +.BR pmlogmerge +intervals). The default value is +.BR 90days . + +.SS PMLOGGER CONFIGURATION + +This group of configuration options controls a +.BR pmlogger +daemon for each host. This may include generating its configuration, +and managing its archives. + +.TP +pmlogger +If and only if this file exists, pmmgr will maintain a +.BR pmlogger +daemon for each +targeted host. This file contains one line of additional space-separated options +for the pmie daemon. (pmmgr already adds \-h, \-f, \-r, \-l, and perhaps \-c.) The +default is to maintain +.BR "no pmlogger" +(and no other configuration in this section is processed). + +.TP +pmlogconf +If and only if this file exists, pmmgr will run +.BR pmlogconf +to generate a configuration +file for each target pmcd. The file contains one line of space-separated additional +options for the pmlogconf program. pmlogconf's generated output file will be stored under +the log\-directory/hostid subdirectory. (pmmgr already adds \-c, \-r, and \-h.) The +default is +.BR "no pmlogconf" , +so instead, the pmlogger file above should probably contain a \-c option, to +specify a fixed pmlogger configuration. + +.SS ARCHIVE LOG MANAGEMENT + +Default pmlogger configurations can collect tens of megabytes of data +per day (possibly split into multiple archives), per target host. If +your disk space is less than infinite, or archive-splitting unwieldy, +this should be managed. In the default, unmanaged case, the system +administrator is responsible for managing the individual +.IR archive-* +files from the per-host logging subdirectories. pmmgr offers several +other options, each representing different performance / usability +tradeoffs. + +.SS ARCHIVE LOG MANAGEMENT - pmlogmerge + +This style of archive log management regularly creates a single merged +archive from prior archives for each target host, in effect lopping +off old data and appending the new. A single merged archive can be +relatively large (defaults to approximately 100-400 MB per host), and +puts a corresponding I/O load on storage, but is most convenient for a +detailed long-timeframe analysis. Once pmlogger is restarted, it +always creates a new archive, so in the steady state, there will be +one merged archive of recent history, and one current archive being +written-to by pmlogger. + +.TP +pmlogmerge +If this file exists, pmmgr will run +.BR pmlogextract +to periodically merge together preexisting log archives for each +target pmcd into a single large one. Then, the preexisting log +archives are deleted (including any prior merged ones). +This configuration file may contain a time interval specification as per the +.IR PCPintro +man page, representing the period after which pmlogger should be temporarily +stopped, and archives merged. It represents the maximum amount of time that +the merged archive \fIlags\fR the present time. The default is +.BR 24hours . + +.TP +pmlogmerge\-granular +If this file exists, pmmgr will merge only a subset of preexisting +log archives into the new one, instead of all of them, so as to +approximate a granular, aligned set of merged archives. The subset +chosen corresponds to the previous time interval specified by the +\fIpmlogmerge\fR control file. +The default is +.BR "no granularity" . + +.TP +pmlogmerge\-retain +If this file exists, pmmgr will set the relative starting time for +retaining old archived data. It will be passed to pmlogextract as a +negative parameter to \-S. It is interpreted as a request that data +older than the given interval should be thrown away. In addition, +unmerged archive files left around, that are older than this, are +deleted. (This can happen if those archive files had errors that +prevented their merging.) The default is +.BR 14days . + +.TP +pmlogmerge\-rewrite +If this file exists, pmmgr will run +.BR "pmlogrewrite -i" +(plus any other options listed in this file) on each input archive before +merging it. This will naturally require more disk I/O. The default is +.BR "no rewriting" . + + +.SS PMIE CONFIGURATION + +This group of configuration options controls a +.BR pmie +daemon for each host. This may include generating a custom +configuration. + +.TP +pmie +If and only if this file exists, pmmgr will maintain a +.BR pmie +daemon for each +targeted pmcd. This file contains one line of additional space-separated options +for the pmie daemon. (pmmgr already adds \-h, \-f, \-l, and perhaps \-c.) The +default is to maintain +.BR "no pmie" +(and no other configuration in this section is processed). + +.TP +pmieconf +If and only if this file exists, pmmgr will run +.BR pmieconf +to generate a configuration +file for each target pmcd. The file contains one line of space-separated additional +options for the pmieconf program. pmieconf's generated output file will be stored under +the log\-directory/hostid subdirectory. (pmmgr already adds \-F, \-c, and \-f.) The +default is +.BR "no pmieconf" , +so instead, the pmie file above should probably contain a \-c option, to +specify a fixed pmie configuration. + +.SH FILES +.PD 0 +.TP 10 +.BI $PCP_SYSCONFIG_DIR/pmmgr/ +default configuration directory +.TP +.BI $PCP_LOG_DIR/pmmgr/ +default logging directory +.PD + +.SH BUGS + + +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parametrize the file and directory names +used by PCP. +On each installation, the file +.I /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). + + +.SH SEE ALSO +.BR PCPIntro (1), +.BR pmcd (1), +.BR pmlogconf (1), +.BR pmlogger (1), +.BR pmieconf (1), +.BR pmie (1), +.BR pmlogreduce (1), +.BR pcp.conf (5) +and +.BR pcp.env (5). diff --git a/man/man1/pmnewlog.1 b/man/man1/pmnewlog.1 new file mode 100644 index 0000000..f1d5a69 --- /dev/null +++ b/man/man1/pmnewlog.1 @@ -0,0 +1,344 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMNEWLOG 1 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmnewlog\f1 \- stop and restart archive logging for PCP performance metrics +.SH SYNOPSIS +\f3$PCP_BINADM_DIR/pmnewlog\f1 +[\f3\-a\f1 \f2accessfile\f1] +[\f3\-C\f1 \f2saveconfig\f1] +[\f3\-c\f1 \f2configfile\f1] +[\f3\-N\f1] +[\f3\-n\f1 \f2pmnsfile\f1] +[\f3\-P\f1] +[\f3\-p\f1 \f2pid\f1] +[\f3\-s\f1] +[\f3\-V\f1] +[\f2other pmlogger options\f1] +\f2archive\f1 +.SH DESCRIPTION +.B pmnewlog +may be used to stop and restart a running instance of +.BR pmlogger (1). +This is most useful for managing multiple sets of +Performance Co-Pilot (PCP) archive logs. +These archive logs record the history of +performance metric values +that may be ``played back'' by other PCP +tools, and they +form the basis of the VCR paradigm and retrospective +performance analysis services common to the PCP toolkit. +.PP +In normal usage, +.B pmnewlog +would be executed by +.BR cron (1) +in the wee hours to terminate one PCP archive log and start another, +i.e. to perform log rotation. +.PP +Even more common, would be the execution of +.B pmnewlog +from the PCP archive management script +.BR pmlogger_daily (1). +In this case, direct end-user execution of +.B pmnewlog +is most unlikely. +.PP +The mandatory argument +.I archive +is the base name for the physical files that will constitute +the new archive log. +.PP +The +.B pmlogger +instance to be stopped and restarted must be running on the same system +as +.B pmnewlog +and is either the primary logger (the default) or the logger with +.I pid +as specified by the +.B \-p +option. +.PP +If the +.B \-n +option is specified, then +.B pmnewlog +will use the namespace in the +.IR pmnsfile , +rather than the default Performance Metrics Name Space (PMNS). +.PP +If no +.B \-c +option is specified, +.B pmnewlog +will use +.BR pmlc (1) +to connect to the running +.BR pmlogger (1) +and so determine all those metrics and instances that are subject to +.B mandatory +logging or +.B advisory on +logging, and the associated logging frequencies. +This information is used to synthesize a new +.BR pmlogger (1) +configuration file. +If the +.B \-n +option is specified, it will also be used for these interactions with +.BR pmlc (1). +.PP +If the +.B \-c +option is specified, +.BR pmlogger (1) +will be restarted with +.I configfile +as the configuration file. +Normally +.I configfile +would be the same configuration file used to start +.BR pmlogger (1) +in the first place, however note that since +.BR pmlogger (1) +is restarted, any changes to the logging status made +using +.BR pmlc (1) +will be lost, unless these have also been reflected in changes to +.IR configfile . +.PP +If +.I configfile +does not exist, then a search is made in the directory +.I $PCP_SYSCONF_DIR/pmlogger +for a file of the same name, and if found that file is used, +e.g. if +.I config.mumble +does not exist in the current directory and +the file +.I $PCP_SYSCONF_DIR/pmlogger/config.mumble +does exist, then +.B "\-c config.mumble" +and +.B "\-c $PCP_SYSCONF_DIR/pmlogger/config.mumble" +are equivalent. +.PP +Access controls specifications for the new +.BR pmlogger (1) +instance may optionally be provided via the +.B \-a +option. The contents of +.I accessfile +should start with the literal token +.B [access] +and conform to the syntax of the access controls section +as described for +.BR pmlogger (1). +.PP +The +.B \-C +option may be used to save the configuration file that +.B pmnewlog +passes to the newly launched +.BR pmlogger (1). +.PP +If the +.BR pmlogger (1) +instance needs to be started under the control of +.BR pmsocks (1) +to connect to a +.B pmcd +through a firewall, the +.B \-s +option may be used. +.PP +The +.B \-V +option enables verbose reporting of the activity. +By default no output is generated unless some error or warning condition is +encountered. +.PP +The +.B \-N +option enables a ``show me'' mode, where the actions are echoed, +but not executed, in the style of ``make \-n''. +Using +.B \-N +in conjunction with +.B \-V +maximizes the diagnostic capabilities for debugging. +.PP +The +.I other pmlogger options +are as described for +.BR pmlogger (1). +Note that +.B pmnewlog +does +.B not +support the following options of +.BR pmlogger (1). +.TP +\fB\-h\fR \fIhost\fR +.B pmnewlog +determines the host to which the new +.BR pmlogger (1) +should connect based upon the current host connection for the +old +.BR pmlogger (1). +.TP +\fB\-s\fR \fIsamples\fR +The new +.BR pmlogger (1) +is expected to be long running, and the +.B \-s +option of +.B pmnewlog +takes precedence. +.TP +\fB\-T\fR \fIruntime\fR +The new +.BR pmlogger (1) +is expected to be long running +.TP +\fB\-V\fR \fIversion\fR +The new +.B pmlogger +will always create the latest version PCP archive format, and the +.B \-V +option of +.B pmnewlog +takes precedence. +.TP +\fB\-x\fR \fIfd\fR +The launched +.B pmlogger +cannot be controlled by +.BR pmRecordControl (3). +.SH EXAMPLE +The following +.BR sh (1) +script +could be executed by root via +.BR cron (1) +to start a new set of archive logs for the primary logger each evening. +A more complete version of this script may be found in +.IR $PCP_BINADM_DIR/pmlogger_daily , +and is documented in the manual page for +.BR pmlogger_daily (1). +.PP +.in +8n +.nf +.ft CW +#!/bin/sh +# start new logs for PCP primary logger on this host + +# standard place for logs +LOGDIR=$PCP_LOG_DIR/pmlogger/`hostname` + +# each new log is named yymmdd.hh.mm +LOGNAME=`date "+%Y%m%d.%H.%M"` + +# do it +[ ! \-d $LOGDIR ] && mkdir \-p $LOGDIR +cd $LOGDIR +$PCP_BINADM_DIR/pmnewlog \-l $LOGDIR/pmlogger.log $LOGDIR +.ft R +.fi +.in -8n +.SH FILES +.PD 0 +.TP 10 +\f2archive\f3.meta +metadata (metric descriptions, instance domains, etc.) for the archive log +.TP +\f2archive\f3.0 +initial volume of metrics values (subsequent volumes have suffixes +.BR 1 , +.BR 2 , +\&...) +.TP +\f2archive\f3.index +temporal index to support rapid random access to the other files in the +archive log +.TP +.B $PCP_BINADM_DIR/pmlogger_daily +sample script to rotate archives for a number of loggers +.PD +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.I /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). +.SH SEE ALSO +.BR PCPIntro (1), +.BR pmcd (1), +.BR pmdumplog (1), +.BR pmlc (1), +.BR pmlogger (1), +.BR pmlogger_daily (1), +.BR pmsocks (1), +.BR pcp.conf (5) +and +.BR pcp.env (5). +.SH DIAGNOSTICS +Due to the precious nature of the archive logs, +.B pmnewlog +is rather paranoid in its checking and validation, and will try very +hard to ensure that an appropriately configured +.BR pmlogger (1) +can be restarted, before terminating the existing +.BR pmlogger (1). +.PP +As a consequence of this checking, +.B pmnewlog +tends to generate rather verbose error and warning messages. +.SH CAVEATS +If no +.I configfile +is specified, the method for synthesizing a configuration file using +a +.BR pmlc (1) +connection to the existing +.BR pmlogger (1) +is, of necessity, incomplete. +In particular, +for metrics with dynamic underlying instance domains, +it is not possible to identify a configuration that logs +.B all +instances of a metric all of the time, +so rather the synthesized configuration file requests the continued logging +of the set of instances that exist at the time +.BR pmlogger (1) +is interrogated by +.BR pmnewlog . +.PP +If this situation is a concern, a fixed configuration file should +be used, and passed to +.B pmnewlog +via the +.B \-c +option. diff --git a/man/man1/pmnsadd.1 b/man/man1/pmnsadd.1 new file mode 100644 index 0000000..cac367b --- /dev/null +++ b/man/man1/pmnsadd.1 @@ -0,0 +1,160 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000-2004 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMNSADD 1 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmnsadd\f1 \- add new names to the Performance Co-Pilot PMNS +.\" literals use .B or \f3 +.\" arguments use .I or \f2 +.SH SYNOPSIS +.B $PCP_BINADM_DIR/pmnsadd +[\f3\-d\f1] +[\f3\-n\f1 \f2namespace\f1] +.I file +.SH DESCRIPTION +.BR pmnsmerge (1) +performs the same function as +.B pmnsadd +and is faster, more robust and more flexible. It is therefore recommended that +.BR pmnsmerge (1) +be used instead. +.PP +.B pmnsadd +adds subtree(s) of new names into a Performance Metrics Name Space (PMNS), +as used by the components of the +Performance Co-Pilot (PCP). +.P +Normally +.B pmnsadd +operates on the default Performance Metrics Namespace (PMNS), however +if the +.B \-n +option is specified an alternative namespace is used +from the file +.IR namespace . +.PP +The default PMNS is found in the file +.I $PCP_VAR_DIR/pmns/root +unless the environment variable +.B PMNS_DEFAULT +is set, in which case the value is assumed to be the pathname +to the file containing the default PMNS. +.PP +The new names are specified in the +.IR file , +arguments and conform to the syntax for PMNS specifications, see +.BR pmns (5). +There is one PMNS subtree in each +.IR file , +and the base PMNS pathname to the inserted subtree is identified by the first group +named in each +.IR file , +e.g. if the specifications begin +.P +.sp 0.5v +.in +1i +.ft CW +.nf +myagent.foo.stuff { + mumble 123:45:1 + fumble 123:45:2 +} +.fi +.ft 1 +.in -1i +.sp 0.5v +.P +then the new names will be added into the PMNS at the non-leaf position +identified by +.ft CW +myagent.foo.stuff\c +.ft 1 +, and following all other names with the prefix +.ft CW +myagent.foo\c +.ft 1 +\&. +.PP +The new names must be contained within a single subtree of the namespace. +If disjoint subtrees need to be added, these must be packaged into separate +files and +.B pmnsadd +used on each, one at a time. +.PP +All of the files defining the PMNS must be located within the directory +that contains the root of the PMNS, +this would typically be +.B $PCP_VAR_DIR/pmns +for the default PMNS, and this would typically imply running +.B pmnsadd +as root. +.PP +As a special case, if +.I file +contains a line that begins +.ft CW +root { +.ft R +then it is assumed to be a complete PMNS that needs to be +merged, so none of the subtree extraction and rewriting is performed and +.I file +is handed directly to +.BR pmnsmerge (1). +.PP +Provided some initial integrity checks are satisfied, +.B pmnsadd +will update the PMNS using +.BR pmnsmerge (1) +\- if this fails for any reason, the original namespace remains +unchanged. +.PP +The +.B \-d +option allows the resultant PMNS to optionally contain +duplicate PMIDs with different names in the PMNS. By default +this condition is considered an error. +.SH CAVEAT +Once the writing of the new +.I namespace +file has begun, the signals SIGINT, SIGHUP and SIGTERM will be ignored +to protect the integrity of the new files. +.SH FILES +.PD 0 +.IP \f2$PCP_VAR_DIR/pmns/root\f1 2.5i +the default PMNS, when then environment variable +.B PMNS_DEFAULT +is unset +.PD +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.I /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). +.SH SEE ALSO +.BR pmnsdel (1), +.BR pmnsmerge (1), +.BR pcp.conf (5), +.BR pcp.env (5) +and +.BR pmns (5). diff --git a/man/man1/pmnsdel.1 b/man/man1/pmnsdel.1 new file mode 100644 index 0000000..91c05d0 --- /dev/null +++ b/man/man1/pmnsdel.1 @@ -0,0 +1,108 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000-2004 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMNSDEL 1 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmnsdel\f1 \- delete a subtree of names from the Performance Co-Pilot PMNS +.\" literals use .B or \f3 +.\" arguments use .I or \f2 +.SH SYNOPSIS +.B $PCP_BINADM_DIR/pmnsdel +[\f3\-d\f1] +[\f3\-n\f1 \f2namespace\f1] +.I metricpath +[ ... ] +.SH DESCRIPTION +.B pmnsdel +removes subtrees of names from a Performance Metrics Name Space (PMNS), +as used by the components of the +Performance Co-Pilot (PCP). +.P +Normally +.B pmnsdel +operates on the default Performance Metrics Namespace (PMNS), however +if the +.B \-n +option is specified an alternative namespace is used +from the file +.IR namespace . +.PP +The default PMNS is found in the file +.I $PCP_VAR_DIR/pmns/root +unless the environment variable +.B PMNS_DEFAULT +is set, in which case the value is assumed to be the pathname +to the file containing the default PMNS. +.PP +The metric names to be deleted are all those for which one of the +.IR metricpath +arguments is +a prefix in the PMNS, see +.BR pmns (5). +.PP +All of the files defining the PMNS must be located within the +directory that contains the root of the PMNS, and this would typically be +.B $PCP_VAR_DIR/pmns +for the default PMNS, and this would typically imply running +.B pmnsdel +as root. +.PP +Provided some initial integrity checks are satisfied, +.B pmnsdel +will update the necessary PMNS files. +Should an error be encountered +the original namespace is restored. Note +that any PMNS files that are no longer referenced by the modified namespace +will not be removed, even though their contents are +not part of the new namespace. +.PP +The +.B \-d +option allows the resultant PMNS to optionally contain +duplicate PMIDs with different names in the PMNS. By default +this condition is considered an error. +.SH CAVEAT +Once the writing of the new +.I namespace +file has begun, the signals SIGINT, SIGHUP and SIGTERM will be ignored +to protect the integrity of the new files. +.SH FILES +.PD 0 +.IP \f2$PCP_VAR_DIR/pmns/root\f1 2.5i +the default PMNS, when then environment variable +.B PMNS_DEFAULT +is unset +.PD +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.I /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). +.SH SEE ALSO +.BR pmnsadd (1), +.BR pmnsmerge (1), +.BR pcp.conf (5), +.BR pcp.env (5) +and +.BR pmns (5). diff --git a/man/man1/pmnsmerge.1 b/man/man1/pmnsmerge.1 new file mode 100644 index 0000000..f1d0253 --- /dev/null +++ b/man/man1/pmnsmerge.1 @@ -0,0 +1,179 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000-2004 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMNSMERGE 1 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmnsmerge\f1 \- merge multiple versions of a Performance Co-Pilot PMNS +.SH SYNOPSIS +.B $PCP_BINADM_DIR/pmnsmerge +[\f3\-adfv\f1] +.I infile +[...] +.I outfile +.SH DESCRIPTION +.B pmnsmerge +merges multiple instances of a +Performance Metrics Name Space (PMNS), +as used by the components of the +Performance Co-Pilot (PCP). +.P +Each +.I infile +argument names a file that includes the root of a PMNS, of the form +.P +.sp 0.5v +.in +1i +.ft CW +.nf +root { + /* arbitrary stuff */ +} +.fi +.ft 1 +.in -1i +.sp 0.5v +.P +The order in which the +.I infile +files are processed is determined by the presence or absence of +embedded control lines of the form +.ft CW +#define _DATESTAMP \f(COYYYYMMDD\fP +.ft 1 +.P +Files without a control line are processed first and in the +order they appear on the command line. +The other files are then processed in order of ascending +\f(CW_DATESTAMP\fP. +.P +The +.B \-a +option suppresses the argument re-ordering and processes all files +in the order they appear on the command line. +.P +The merging proceeds by matching names in PMNS, only those +\fBnew\fP names in each PMNS are considered, and these are +added after any existing metrics with the longest possible +matching prefix in their names. +For example, merging these two input PMNS +.P +.sp 0.5v +.in +1i +.ft CW +.nf +root { root { + surprise 1:1:3 + mine 1:1:1 mine 1:1:1 + foo foo + yawn + yours 1:1:2 +} } +foo { foo { + fumble 1:2:1 + mumble 1:2:3 + stumble 1:2:2 stumble 1:2:2 +} } + yawn { + sleepy 1:3:1 + } +.fi +.ft 1 +.in -1i +.P +Produces the resulting PMNS in +.IR out . +.P +.sp 0.5v +.in +1i +.ft CW +.nf +root { + mine 1:1:1 + foo + yours 1:1:2 + surprise 1:1:3 + yawn +} +foo { + fumble 1:2:1 + stumble 1:2:2 + mumble 1:2:3 +} +yawn { + sleepy 1:3:1 +} +.fi +.ft 1 +.P +To avoid accidental over-writing of PMNS files, +.I outfile +is expected to not exist when +.B pmnsmerge +starts. +The +.B \-f +option forces the removal of +.I outfile +(if it exists), before the check is made. +.PP +The +.B \-d +option allows the resultant PMNS to optionally contain +duplicate PMIDs with different names in the PMNS. By default +this condition is considered an error. +.PP +The +.B \-v +option produces one line of diagnostic output as each +.I infile +is processed. +.PP +Once all of the merging has been completed, +.B pmnsmerge +will attempt to load +the resultant namespace using +.BR pmLoadASCIINameSpace (3) +\- if this fails for any reason, +.I outfile +will still be created, but +.B pmnsmerge +will report the problem and exit with non-zero status. +.SH CAVEAT +Once the writing of the new +.I outfile +file has begun, the signals SIGINT, SIGHUP and SIGTERM will be ignored +to protect the integrity of the new file. +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.I /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). +.SH SEE ALSO +.BR pmnsadd (1), +.BR pmnsdel (1), +.BR pmLoadASCIINameSpace (3), +.BR pcp.conf (5), +.BR pcp.env (5) +and +.BR pmns (5). diff --git a/man/man1/pmpost.1 b/man/man1/pmpost.1 new file mode 100644 index 0000000..e36cfe6 --- /dev/null +++ b/man/man1/pmpost.1 @@ -0,0 +1,79 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2013 Red Hat. +.\" Copyright (c) 2000-2004 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.TH PMPOST 1 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmpost\f1 \- append messages to the Performance Co-Pilot notice board +.\" literals use .B or \f3 +.\" arguments use .I or \f2 +.SH SYNOPSIS +.B $PCP_BINADM_DIR/pmpost +.I message +.SH DESCRIPTION +.B pmpost +will append the text +.I message +to the end of the +Performance Co-Pilot (PCP) notice board file (\c +.BR $PCP_LOG_DIR/NOTICES ) +in an atomic manner that guards against corruption of +the notice board file +by concurrent invocations of +.BR pmpost . +.PP +The PCP notice board is intended to be a persistent store +and clearing house for important messages relating to the +operation of the PCP and the notification of performance +alerts from +.BR pmie (1) +when other notification options are either unavailable or +unsuitable. +.PP +Before being written, messages are prefixed by the current +time, and when the current day is different to the last +time the notice board file was written, +.B pmpost +will prepend the message with the full date. +.PP +If the notice board file does not exist, +.B pmpost +will create it. +.B pmpost +would usually run from long-running PCP daemons executing +under the (typically unprivileged) +.B $PCP_USER +and +.B $PCP_GROUP +accounts. +The file should be owned by root, and group writable by the +.B $PCP_GROUP +group. +.SH FILES +.TP 10 +.B $PCP_LOG_DIR/NOTICES +the PCP notice board file +.SH "PCP ENVIRONMENT" +The file +.B /etc/pcp.conf +contains the local values for PCP_ variables. +.SH UNIX SEE ALSO +.BR logger (1). +.SH WINDOWS SEE ALSO +.BR pcp-eventlog (1). +.SH SEE ALSO +.BR pmie (1), +.BR pcp.conf (5) +and +.BR pcp.env (5). diff --git a/man/man1/pmprobe.1 b/man/man1/pmprobe.1 new file mode 100644 index 0000000..58c8e7e --- /dev/null +++ b/man/man1/pmprobe.1 @@ -0,0 +1,267 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000-2004 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMPROBE 1 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmprobe\f1 \- lightweight probe for performance metrics +.SH SYNOPSIS +\f3pmprobe\f1 +[\f3\-fIiLVvz\f1] +[\f3\-a\f1 \f2archive\f1] +[\f3\-h\f1 \f2hostname\f1] +[\f3\-K\f1 \f2spec\f1] +[\f3\-n\f1 \f2pmnsfile\f1] +[\f3\-O\f1 \f2time\f1] +[\f3\-Z\f1 \f2timezone\f1] +[\f2metricname\f1 ...] +.SH DESCRIPTION +.B pmprobe +determines the availability of performance metrics +exported through the facilities of the Performance Co-Pilot (PCP). +.PP +The metrics of interest are named in the +.I metricname +arguments. +If +.I metricname +is a non-leaf node in the Performance Metrics Name Space (\c +.BR pmns (5)), +then +.B pmprobe +will recursively descend the PMNS and report on all leaf nodes. +If no +.I metricname +argument is given, the root of the namespace is used. +.PP +The output format is spartan and intended for use in wrapper +scripts creating configuration files for other PCP tools. +By default, there is one line of output per metric, with the +metric name followed by a count of the number of available values. +Error conditions are encoded as a negative value count (as +per the +.BR PMAPI (3) +protocols, but may be decoded using +.BR pmerr (1)) +and followed by a textual description of the error. +.PP +Unless directed to another host by the +.B \-h +option, +.B pmprobe +will contact the Performance Metrics Collector Daemon +(PMCD) on the local host. +.PP +The +.B \-a +option causes +.B pmprobe +to use the specified archive rather than connecting to a PMCD. The +.B \-a +and +.B \-h +options are mutually exclusive. +.PP +The +.B \-L +option causes +.B pmprobe +to use a local context to collect metrics from PMDAs on the local host +without PMCD. Only some metrics are available in this mode. +The +.BR \-a , \-h +and +.B \-L +options are mutually exclusive. +.PP +Normally +.B pmprobe +operates on the distributed Performance Metrics Name Space (PMNS), +however, if the +.B \-n +option is specified an alternative local PMNS file is loaded +from the file +.IR pmnsfile . +.PP +Other options control the output of additional information when +one or more values is available. +.TP 5 +.B \-f +When used with +.B \-i +or +.B \-I +the set of instances reported will be all of those known at the +source of the performance data. By default the set of reported +instances are those for which values are currently available, which +may be smaller than the set reported with +.BR \-f . +.TP +.B \-I +Report the external identifiers for each instance. The literal string +.B PM_IN_NULL +is reported for singular metrics. +.TP +.B \-i +Report the internal identifiers for each instance. The values are +in decimal and prefixed by ``?''. As a special case, the literal +string +.B PM_IN_NULL +is reported for singular metrics. +.TP +.B \-K +When using the +.B \-L +option to fetch metrics from a local context, the +.B \-K +option may be used to control the DSO PMDAs that should be +made accessible. The +.I spec +argument conforms to the syntax described in +.BR __pmSpecLocalPMDA (3). +More than one +.B \-K +option may be used. +.TP +.B \-O +When used in conjunction with an archive source of metrics and +the +.B \-v +option the +.I time +argument defines a time origin at which the metrics should be +fetched from the archive. +Refer to +.BR PCPIntro (1) +for a complete description of this option, and the syntax for the +.I time +argument. +.RS +.PP +When the ``ctime'' format is used for the +.I time +argument in a +.B \-O +option, the timezone becomes an issue. +The default is to use the +local timezone on the +system where +.B pmprobe +is run. +The +.B \-Z +option changes the timezone to +.I timezone +in the format of the environment variable +.B TZ +as described in +.BR environ (5). +The +.B \-z +option changes the timezone to the local timezone at the +host that is the source of the performance metrics, as identified via +the +.B \-a +option. +.RE +.TP +.B \-v +Report the value for each instance, as per the formatting +rules of +.BR pmPrintValue (3). +When fetching from an archive, only +those instances present in the first archive record for a metric will be +displayed; see also the +.B \-O +option. +.PP +The +.B \-v +option is mutually exclusive with either the +.B \-I +or +.B \-i +options. +.PP +The +.B \-V +option provides a cryptic summary of the number of messages sent +and received across the PMAPI interface. +.SH EXAMPLES +.nf +.ft CW +$ pmprobe disk.dev +.ft CW +disk.dev.read 2 +disk.dev.write 2 +disk.dev.total 2 +disk.dev.blkread 2 +disk.dev.blkwrite 2 +disk.dev.blktotal 2 +disk.dev.active 2 +disk.dev.response 2 +.sp +.ft CW +$ pmprobe \-I disk.dev.read disk.dev.write disk.all.total +.ft CW +disk.dev.read 2 "dks0d1" "dks0d2" +disk.dev.write 2 "dks0d1" "dks0d2" +disk.all.total 1 PM_IN_NULL +.sp +.ft CW +$ pmprobe \-v pmcd.numagents pmcd.version pmcd.control.timeout +.ft CW +pmcd.numagents 1 9 +pmcd.version 1 "2.0 beta-1" +pmcd.control.timeout 1 5 +.sp +.ft CW +$ pmprobe \-v disk.dev.total disk.all.total +.ft CW +disk.dev.total \-1012 Unknown metric name +disk.all.total 1 4992466 +.fi +.ft R +.SH FILES +.PD 0 +.TP 10 +.BI $PCP_VAR_DIR/pmns/ * +default PMNS specification files +.PD +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.I /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). +.SH SEE ALSO +.BR PCPIntro (1), +.BR pmcd (1), +.BR pmdumplog (1), +.BR pminfo (1), +.BR PMAPI (3), +.BR pmErrStr (3), +.BR __pmSpecLocalPMDA (3), +.BR pcp.conf (5), +.BR pcp.env (5) +and +.BR pmns (5). diff --git a/man/man1/pmproxy.1 b/man/man1/pmproxy.1 new file mode 100644 index 0000000..fa903e6 --- /dev/null +++ b/man/man1/pmproxy.1 @@ -0,0 +1,365 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2013 Red Hat. +.\" Copyright (c) 2000 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMPROXY 1 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmproxy\f1 \- proxy for performance metrics collector daemon +.SH SYNOPSIS +\f3pmproxy\f1 +[\f3\-C\f1 \f2dirname\f1] +[\f3\-f\f1] +[\f3\-i\f1 \f2ipaddress\f1] +[\f3\-l\f1 \f2logfile\f1] +[\f3\-L\f1 \f2bytes\f1] +[\f3\-p\f1 \f2port\f1[,\f2port\f1 ...] +[\f3\-P\f1 \f2passfile\f1] +[\f3\-U\f1 \f2username\f1] +[\f3\-x\f1 \f2file\f1] +.SH DESCRIPTION +.B pmproxy +acts as a protocol proxy for +.BR pmcd (1), +allowing Performance Co-Pilot (PCP) monitoring clients to connect to +one or more +.BR pmcd (1) +instances via +.BR pmproxy . +.PP +Normally +.B pmproxy +is deployed in a firewall domain, or on a ``head'' node of a cluster +where the IP (Internet Protocol) address of the hosts where +.BR pmcd (1) +is running may be unknown to the PCP monitoring clients, although the +IP address of the host where +.B pmproxy +is running is known to these clients. +Similarly, the clients may have network connectivity only to the +host where +.B pmproxy +is running, while there is network connectivity from that host to the +hosts of interest where +.BR pmcd (1) +is running. +.PP +The behaviour of the PCP monitoring clients is controlled by either the +.B PMPROXY_HOST +environment variable or through the extended hostname specification +(see +.BR PCPIntro (1) +for details). +If neither of these mechanisms is used, clients will make their +connections directly to +.BR pmcd (1). +If the proxy hostname syntax is used or +.B PMPROXY_HOST +is set, then this should be the hostname or IP address of the system +where +.B pmproxy +is running, and the clients will connect to +.BR pmcd (1) +indirectly through the protocol proxy services of +.BR pmproxy. +.PP +The options to +.B pmproxy +are as follows. +.TP +\f3\-C\f1 \f2dirname\f1 +Specify the path to the Network Security Services certificate database, +for (optional) secure connections. +The default is +.BR /etc/pki/nssdb . +Refer also to the \f3\-P\f1 option. +If it does not already exist, this database can be created using the +.B certutil +utility. +This process and other certificate database maintenance information +is provided in the +.BR PCPIntro (1) +manual page and the online PCP tutorials. +.TP +.B \-f +By default +.B pmproxy +is started as a daemon. +The +.B \-f +option indicates that it should run in the foreground. +This is most useful when trying to diagnose problems with establishing +connections. +.TP +\f3\-i\f1 \f2ipaddress\f1 +This option is usually only used on hosts with more than one network +interface (very common for firewall and ``head'' node hosts where +.B pmproxy +is most likely to be deployed). If no +.B \-i +options are specified +.B pmproxy +accepts PCP client connections on any of its host's IP addresses. +The +.B \-i +option is used to specify explicitly an IP address that PCP client connections should be +accepted on. +.I ipaddress +should be in the standard dotted form (e.g. 100.23.45.6). The +.B \-i +option may be used multiple times to define a list of IP addresses. +When one or more +.B \-i +options is specified, attempted connections made on any other IP addresses will be refused. +.TP +\f3\-l\f1 \f2logfile\f1 +By default a log file named +.I pmproxy.log +is written in the current directory. +The +.B \-l +option causes the log file to be written to +.I logfile +instead of the default. +If the log file cannot be created or is not writable, output is +written to the standard error instead. +.TP +\f3\-L\f1 \f2bytes\f1 +.IR PDU s +received by +.B pmproxy +from PCP monitoring clients are restricted to a +maximum size of 65536 bytes by default to defend against Denial of +Service attacks. The +.B \-L +option may be used to change the maximum incoming +.I PDU +size. +.TP +\f3\-P\f1 \f2passfile\f1 +Specify the path to a file containing the Network Security Services certificate +database password for (optional) secure connections, and for databases that are +password protected. +Refer also to the \f3\-C\f1 option. +When using this option, great care should be exercised to ensure appropriate +ownership ("pcp" user, typically) and permissions on this file (0400, so as to +be unreadable by any user other than the user running the +.B pmproxy +process). +.TP +\f3\-U\f1 \f2username\f1 +Assume the identity of +.I username +before starting to accept incoming packets from PCP monitoring clients. +.TP +\f3\-x\f1 \f2file\f1 +Before the +.B pmproxy +.I logfile +can be opened, +.B pmproxy +may encounter a fatal error which prevents it from starting. By default, the +output describing this error is sent to +.B /dev/tty +but it may redirected to +.IR file . +.SH "STARTING AND STOPPING PMPROXY" +Normally, +.B pmproxy +is started automatically at boot time and stopped when the +system is being brought down. +Under certain circumstances it is necessary to start or stop +.B pmproxy +manually. +To do this one must become superuser and type +.PP +.ft CS +# $PCP_RC_DIR/pmproxy start +.ft +.PP +to start +.BR pmproxy , +or +.PP +.ft CS +# $PCP_RC_DIR/pmproxy stop +.ft +.PP +to stop +.BR pmproxy . +Starting +.B pmproxy +when it is already running is the same as stopping +it and then starting it again. +.P +Normally +.B pmproxy +listens for PCP client connections on TCP/IP port number 44322 +(registered at +.IR http://www.iana.org/ ). +Either the environment +variable +.B PMPROXY_PORT +.B \-p +command line option +may be used to specify alternative port number(s) when +.B PMPROXY_PORT +or the +.B \-p +command line option +may be used to specify alternative port number(s) when +.B pmproxy +is started; in each case, the specification is a comma-separated list +of one or more numerical port numbers. Should both methods be used +or multiple +.B \-p +options appear on the command line, +.B pmproxy +will listen on the union of the set of ports specified via all +.B \-p +options and the +.B PMPROXY_PORT +environment variable. +If non-default ports are used with +.B pmproxy +care should be taken to ensure that +.B PMPROXY_PORT +is also set in the environment of any client application that +will connect to +.BR pmproxy , +or that the extended host specification syntax is used +(see +.BR PCPIntro (1) +for details). +.SH FILES +.PD 0 +.TP +.B PCP_PMPROXYOPTIONS_PATH +command line options +and environment variable settings for +.B pmproxy +when launched from +.B $PCP_RC_DIR/pmproxy +All the command line option lines should start with a hyphen as +the first character. +This file can also contain environment variable settings of +the form "VARIABLE=value". +.TP +.B \&./pmproxy.log +(or +.B $PCP_LOG_DIR/pmproxy/pmproxy.log +when started automatically) +.br +All messages and diagnostics are directed here +.TP +.B /etc/pki/nssdb +default Network Security Services (NSS) certificate database +directory, used for optional Secure Socket Layer connections. +This database can be created and queried using the NSS +.B certutil +tool, amongst others. +.PD +.SH ENVIRONMENT +In addition to the PCP environment variables described in the +.B "PCP ENVIRONMENT" +section below, there are several environment variables that +influence the interactions between a PCP monitoring client, +.B pmcd +and +.BR pmcd (1). +.TP +.B PMCD_PORT +For the PCP monitoring client this (or the default port number) is passed to +.B pmproxy +and used to connect to +.BR pmcd (1). +In the environment of +.B pmproxy +.B PMCD_PORT is not used. +.TP +.B PMPROXY_HOST +For the PCP monitoring client this is the hostname or IP address of the +host where +.B pmproxy +is running. +In recent versions of PCP (since version 3) this has been superseded by +the extended hostname syntax +(see +.BR PCPIntro (1) +for details). +.TP +.B PMPROXY_PORT +For the PCP monitoring client this is the port on which +.B pmproxy +will accept connections. The default is 44322. +.TP +.BR PMCD_CONNECT_TIMEOUT ", " PMCD_RECONNECT_TIMEOUT " and " PMCD_REQUEST_TIMEOUT +(see +.BR PCPIntro (1)) +For the PCP monitoring client, setting these environment variables +will modify the timeouts used for interactions between the client +and +.BR pmproxy +(independent of which +.BR pmcd (1) +is being used). +For +.B pmproxy +these same environment variables control the timeouts between +.B pmproxy +and all +.BR pmcd (1) +instances (independent of which monitoring client is involved). +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.B /etc/pcp.conf +contains the local values for these variables. +The +.B PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). +.SH SEE ALSO +.BR PCPIntro (1), +.BR pmcd (1), +.BR pmdbg (1), +.BR pcp.conf (5) +and +.BR pcp.env (5). +.SH DIAGNOSTICS +If +.B pmproxy +is already running the message "Error: OpenRequestSocket bind: Address already +in use" will appear. +This may also appear if +.B pmproxy +was shutdown with an outstanding request from a client. +In this case, a +request socket has been left in the TIME_WAIT state and until the system closes +it down (after some timeout period) it will not be possible to run +.BR pmproxy . +.PP +In addition to the standard +.B PCP +debugging flags, see +.BR pmdbg (1), +.B pmproxy +currently uses +.B DBG_TRACE_CONTEXT +for tracing client connections and disconnections diff --git a/man/man1/pmquery.1 b/man/man1/pmquery.1 new file mode 100644 index 0000000..9644e84 --- /dev/null +++ b/man/man1/pmquery.1 @@ -0,0 +1,252 @@ +.TH PMQUERY 1 "" "Performance Co-Pilot" +.SH NAME +\f3pmconfirm\f1, \f3pmmessage\f1, \f3pmquery\f1 \- general purpose dialog box +.SH SYNOPSIS +\f3pmconfirm\f1 +[\f3\-c\f1] +[\f3\-b\f1 \f2button-name\f1] +[\f3\-B\f1 \f2default-button-name\f1] +[\f3\-t\f1 \f2string\f1] +[\f3\-file\f1 \f2filename\f1] +[\f3\-icon\f1 \f2icontype\f1] +[\f3\-font\f1 \f2font\f1] +[\f3\-header\f1 \f2titlebar-string\f1] +[\f3\-useslider\f1] +[\f3\-noslider\f1] +[\f3\-noframe\f1] +[\f3\-exclusive\f1] +.br +.PP +\f3pmmessage\f1 +[\f3\-buttons\f1 \f2label1\f1[:\f2value1\f1][,\f2label2\f1[:\f2value2\f1][,...]]] +[\f3\-center\f1] +[\f3\-nearmouse\f1] +[\f3\-default\f1 \f2button\f1] +[\f3\-file\f1 \f2filename\f1] +[\f3\-print\f1] +[\f3\-timeout\f1 \f2sec\f1] +.I message... +.br +.PP +\f3pmquery +[\f3\-input\f1] +[\f3all above options...\f1] +[\f2message...\f1] +.SH DESCRIPTION +.B pmquery +provides a command-line-option compatible implementation of the +.B xconfirm +and +.B xmessage +tools, using a look-and-feel that is consistent with +.BR pmchart . +Several extensions to the functionality of the original tools have been made, +in order to improve their specific utility for +.BR pmchart , +but wherever possible the original semantics remain. +.PP +.B pmconfirm +displays a line of text for each +.I \-t +argument specified (or a file when the +.I \-file +argument is used), +and a button for each +.I \-b +argument specified. +When one of the buttons is pressed, the label of that button is written to +.B pmquery's +standard output. +This provides a means of communication/feedback from within shell +scripts and a means to display useful information to a user from +an application. +.PP +.B pmmessage +displays a window containing a message from the command line, a file, +or standard input. +It additionally allows buttons to be associated with an exit status, +and only optionally will write the label of the button to standard output. +.PP +.B pmquery +extends the above tools to additionally support limited user input, +as free form text. +In this +.B \-input +mode, any text entered will be output when the default button is pressed. +A default text can be entered using the same mechanisms as the other tools. +.PP +Command line options are available to specify font style, frame style, +modality and one of several different icons to be presented for tailored +visual feedback to the user. +.TP 5 +.B \-c \f1or \f3\-center\f1 +Center the window on the display. +.TP +.B \-nearmouse +Pop up the window near the mouse cursor. +.TP +.B \-b \f2button-name\f1 +Displays a button with the label +.IR button-name . +If +.I button-name +is the empty string, the button in that position is not displayed. +If no +.B \-b +arguments are present, the default is a button with the label Continue. +The exit status associated with +.I button-name +is zero. +.TP +.B \-B \f2button-name\f1 +Displays a button with the label +.I button-name +and specifies it as the button to be activated when enter is pressed. +The exit status associated with +.I button-name +is zero. +.TP +.B \-buttons \f2button,button,.\|.\|.\f1 +This option will create one button for each comma-separated \f2button\f1 +argument. +Each \f2button\f1 consists of a label optionally followed by a colon +and an exit value. +The exit value will be returned if that button is selected. +The default exit value is 100 plus the button number. +Buttons are numbered from the left starting with one. +.TP +.B \-default \fIlabel\fP +Defines the button with a matching \fIlabel\fP to be the default. +If not specified there is no default. +The corresponding resource is \fBdefaultButton\fP. +Pressing Return anywhere in the \fIxmessage\fP window will activate +the default button. +The default button has a wider border than the others. +.TP +.B \-t \f2message\f1 +Displays message. +Any number of strings can be listed on the command line +(each must be preceded with the +.B \-t +option). +.TP +.B \-file \f2filename\f1 +Displays the file +.I filename. +All +.B \-t +options will be ignored. +A \f2filename\f1 of `\f2\-\f1' reads from standard input. +.TP +.B \-icon \f2icontype\f1 +Displays the icon +.I icontype +where icontype is one of: +.IR info , +.IR error , +.IR question , +.IR warning , +.IR critical . +.I action +is also accepted as a synonym for +.I error +for backward compatibility. +.BR pmquery +introduces the additional +.I archive +and +.I host +icon types as well as the original +.BR xconfirm +types listed earlier. +.TP +.B \-font \f2fontname\f1 +Use fontname as the font. +This option is only available when using the X Window System. +.TP +.B \-header \f2string\f1 +Use string as the window title. +.TP +.B \-print +This causes the program to write the label of the button pressed to +standard output. +It is the default behaviour for +.B pmconfirm +and +.BR pmquery . +.TP +.B \-noprint +This causes the program to not write the label of the button pressed to +standard output. +It is the default behaviour for +.BR pmmessage . +.TP +.B \-geometry \f2geometry-string\f1 +This provides xconfirm with an X-compatible geometry string specification. +This option is only available when using the X Window System. +.TP +.B \-useslider +When displaying a file, always use a slider instead of determining +automatically whether a slider is necessary. +.TP +.B \-noslider +Do not create a slider, and clip text to the window size, instead of +determining automatically whether a slider is necessary.. +.TP +.B \-noframe +Do not display a frame around the contents. +.TP +.B \-exclusive +Grab the keyboard/pointer and do not allow further +input until a button is pressed. +.TP +.B \-timeout \f2secs\f1 +Exit with status 0 after \fIsecs\fP seconds if the user has not +clicked on a button yet. +The corresponding resource is \fBtimeout\fP. +.SH EXAMPLES +The following shell script will display a window with an information icon, +asking the user a yes or no question with "Yes" as the default. +.PP +.nf + #! /bin/sh + case `pmquery \-t "Really power down?" \-b No \-B Yes \-icon question + in + Yes) shutdown;; + No) ;; + esac +.fi +.PP +A second example, which prompts for a hostname then starts a +terminal with an ssh session connected to the requested host. +.PP +.nf + #! /bin/sh + host=`pmquery \-input \-icon host \-b Cancel \-B OK \\ + \-header "Remote Terminal \- Secure Shell" + [ "$host" = "Cancel" \-o \-z "$host" ] && exit + gnome-terminal \-e "ssh $host" +.fi +.SH ENVIRONMENT +.B pmquery +is an excellent choice of utility for the "PCP_XCONFIRM_PROG" +Performance Co-Pilot configuration parameter (refer to +.BR pcp.conf (4) +for details). +.PP +Note that PCP_XCONFIRM_PROG will be automatically set to +.B pmquery +inside tools like +.BR pmchart , +unless PCP_XCONFIRM_PROG is already set in the environment. +.SH "EXIT STATUS" +If it detects an error, +.B pmquery +always returns 1, so this value should not be associated with a button. +Unless \f2\-button\f1 option has not been used, the return code will be +zero on success. +.SH "SEE ALSO" +.BR pmchart (1), +.BR xconfirm (1), +.BR xmessage (1), +.BR pcp.conf (4). diff --git a/man/man1/pmsignal.1 b/man/man1/pmsignal.1 new file mode 100644 index 0000000..faa208c --- /dev/null +++ b/man/man1/pmsignal.1 @@ -0,0 +1,67 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2009 Aconex. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.TH PMSIGNAL 1 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmsignal\f1 \- send a signal to one or more processes +.SH SYNOPSIS +\f3$PCP_BINADM_DIR/pmsignal\f1 +[\f3\-a\f1|\f3-l\f1] +[\f3\-n\f1] +[\f3\-s\f1 \fIsignal\fR] +[\f2PID\f1 ...|\f2name\f1 ...] +.SH DESCRIPTION +.B pmsignal +provides a cross-platform event signalling mechanism for use with +tools from the Performance Co-Pilot toolkit. +It can be used to send a named +.I signal +(only HUP, USR1, TERM, and KILL are accepted). +to one or more processes. +The processes are specified using PID or the binary name (with +.B \-a +option). +.PP +If a +.I signal +is not specified, then the TERM signal will be sent. +.PP +On Linux and UNIX platforms, +.I pmsignal +is a simple wrapper around the +.IR kill (1) +command. +On Windows, the is no direct equivalent to this mechanism, and +so an alternate mechanism has been implemented \- this is only +honoured by PCP tools, however, not all Windows utilities. +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.I /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). +.SH SEE ALSO +.BR kill (1), +.BR killall (1), +.BR pcp.conf (5) +and +.BR pcp.env (5). diff --git a/man/man1/pmsleep.1 b/man/man1/pmsleep.1 new file mode 100644 index 0000000..3cd4c7d --- /dev/null +++ b/man/man1/pmsleep.1 @@ -0,0 +1,44 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2007 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMSLEEP 1 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmsleep\f1 \- portable subsecond-capable sleep +.\" literals use .B or \f3 +.\" arguments use .I or \f2 +.SH SYNOPSIS +.B $PCP_BINADM_DIR/pmsleep +.I interval +.SH DESCRIPTION +.B pmsleep +sleeps for +.I interval. +The +.I interval +argument follows the syntax described in +.BR PCPIntro (1) +for +.B \-t, +and in the simplest form may be an unsigned integer +or floating point constant +(the implied units in this case are seconds). +.SH DIAGNOSTICS +The exit status is 0 for success, or 1 for a malformed command line. +If the underlying +.B nanosleep (2) +system call fails, an errno is returned. +.SH SEE ALSO +.BR sleep (1), +.BR nanosleep (3). diff --git a/man/man1/pmsnap.1 b/man/man1/pmsnap.1 new file mode 100644 index 0000000..b4a4067 --- /dev/null +++ b/man/man1/pmsnap.1 @@ -0,0 +1,275 @@ +.TH PMSNAP 1 "" "Performance Co-Pilot" +.SH NAME +\f3pmsnap\f1 \- generate performance summary snapshot images +.SH SYNOPSIS +.B $PCP_BINADM_DIR/pmsnap +[\f3\-NV\f1] +[\f3\-C\f1 \f2dir\f1] +[\f3\-c\f1 \f2configs\f1] +[\f3\-n\f1 \f2names\f1] +[\f3\-o\f1 \f2dir\f1] +[\f3\-t\f1 \f2type\f1] +.br +.SH DESCRIPTION +.B pmsnap +is a shell script +that is normally run periodically from +.BR crontab (1) +to generate graphic images of +.BR pmchart (1) +performance charts. +These images can be in any of the supported +.B pmchart +formats, including +.IR png , +.IR bmp , +and +.IR jpeg , +and may be incorporated into the content offered by the local Web server. +The +.B \-V +option enables verbose tracing of the actions. +By default +.B pmsnap +generates no output unless some error or warning condition is encountered. +.PP +.B pmsnap +generates images according to its control file, +.B $PCP_PMSNAPCONTROL_PATH +(or +.B dir/control +if the +.B \-C +option is specified), +and uses archive logs created by +.BR pmlogger (1) +or PCP archive folios created by +.BR pmafm (1) +and +.BR pmlogger_check (1). +Before attempting to configure +.BR pmsnap , +it is strongly recommended that +.B pmlogger +be configured according to the descriptions in +.BR pmlogger_daily (1), +.BR pmlogger_check (1) +and +.BR pmlogger (1). +.P +Once +.B pmlogger +has been configured, +it is necessary to configure +.B pmsnap +as follows; +.IP 1. +Edit the control file +.BR $PCP_PMSNAPCONTROL_PATH . +The syntax of this file is described in the comment at the head of the file +and an example is supplied for one and twelve hour "Summary" performance charts +for the local host. +Suitable arguments for +.B pmchart +are also described in the comment. +The user should consult +.B pmchart +for further details. +Note that when +.B pmsnap +is run, it globally substitutes the string +.B LOCALHOSTNAME +with the name of the local host in the control file. +.IP 2. +Test the configuration by running +.ce 1 +.BR "$PCP_BINADM_DIR/pmsnap" . +Without any arguments +.B pmsnap +will process every non-comment line in +.BR $PCP_PMSNAPCONTROL_PATH . +The output images will be placed in the files named +in the first field of each line in the control file, with the file format +appended if necessary. +If these file names do not start with +.B / +or +.B . +then they are assumed relative to +.IR dir , +as specified with the +.B \-o +option. +The default +.I dir +is the current directory. +Note that if +.B pmlogger +has only been recently started (within about the last 15 minutes), +snap-shot images may not be produced and no error +messages will be issued - the reason is that +.B pmchart +can not use very short archives +and hence, neither can +.BR pmsnap . +For debugging purposes the +.B \-V +flag should be used. +.IP 3. +Add an appropriate entry for +.B pmsnap +in the +.B root +user's +.BR crontab . +An example is supplied in +.BR $PCP_VAR_DIR/config/pmlogger/crontab . +.IP 4. +Incorporate the +.B pmsnap +images into the local WWW content. +Usually, WWW pages use images that are relative to a particular document root, +so it is often convenient to use the +.B \-o +command line option to specify a sub-directory of the local WWW content, +and then create a web page in this directory that shows the +snapshot images with text and other content appropriate to the local +environment. +.SH "COMMAND LINE OPTIONS" +.B pmsnap +accepts the following command line options; +.TP +.BI \-C " dir" +The +.B control +file is located in the directory +.I dir +rather than in the default +.BR $PCP_PMSNAPCONTROL_PATH +location. +.TP +.BI \-c " config-pattern" +Only process lines in the control file +which match the +.I config-pattern +regular expression +in the +.B Config +column. +.TP +.BI \-n " name-pattern" +Only process lines in the control file +which match the +.I name-pattern +regular expression (see +.BR egrep (1)) +in the +.B Name +column. +.TP +.BI \-o " dir" +The output images having file names which do not start +with +.B / +or +.B . +will be placed in a directory relative to +.IR dir , +otherwise the output directory +is relative to the current directory (i.e. the default +value for +.I dir +is +.BR ./ ). +Note that +.I dir +must be a writable directory path +and may be on an NFS or CIFS file system. +.P +The +.B \-N +option enables a ``show me'' mode, where the actions are echoed, +but not executed, in the style of ``make \-n''. +Using +.B \-N +in conjunction with +.B \-V +maximizes the diagnostic capabilities for debugging. +.P +When either +.B \-n +or +.BR \-c +are used, +.B pmsnap +will only process lines in the control file +which match all the supplied patterns. +If no patterns are given, +then all lines will be processed. +These arguments allow multiple entries for +.B pmsnap +in +.B crontab +so that different performance summary images can be generated +at different times or with different frequencies. +.P +A sample HTML page, suitable for the Summary snapshot may be found in +.BR $PCP_VAR_DIR/config/pmsnap/Summary.html . +.P +Although +.B pmsnap +attempts to flush +.BR stdio (3) +output buffers in the relevant +.B pmlogger +processes before generating snap-shots images, +this may fail for assorted reasons and no error message will be given. +.P +.B pmsnap +should not be invoked immediately after +.B pmlogger_daily +has rolled the logs because the new archive logs will be too short +to obtain meaningful results. +Note however that +.B pmsnap +will not report errors from +.B pmchart +about not being able to comply with the +.B \-A +option on very short archives. +In these cases no error will be reported +and no output images will be produced. +.SH FILES +.TP 10 +.B $PCP_PMSNAPCONTROL_PATH +\fBpmsnap\fR control file +.TP +.B $PCP_VAR_DIR/config/pmsnap/Summary +summary view for +.B pmchart +.TP +.B $PCP_VAR_DIR/config/pmsnap/Summary.html +sample HTML page for summary snapshot +.TP +.BI $PCP_LOG_DIR/pmlogger/ hostname /Latest +PCP archive folio for the host +.IR hostname , +as generated by +.B pmlogger_check +.TP +.B $PCP_VAR_DIR/config/pmlogger/crontab +example +.B crontab +entry +.SH SEE ALSO +.BR cron (1), +.BR crontab (1), +.BR egrep (1), +.BR pmchart (1), +.BR pmafm (1), +.BR pmlc (1), +.BR pmlogger (1), +.BR pmlogger_daily (1), +.BR X (1), +and +.BR Xvfb (1). diff --git a/man/man1/pmsocks.1 b/man/man1/pmsocks.1 new file mode 100644 index 0000000..9dce14d --- /dev/null +++ b/man/man1/pmsocks.1 @@ -0,0 +1,328 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000-2004 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMSOCKS 1 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmsocks\f1 \- shell wrapper for performance monitoring across firewalls +.\" literals use .B or \f3 +.\" arguments use .I or \f2 +.SH SYNOPSYS +\f3pmsocks\f1 +\f2path\f1 +[\f2args\f1 ...] +.SH DESCRIPTION +.B pmsocks +allows Performance Co-Pilot (PCP) clients running on +hosts located on the internal side of a TCP/IP firewall to monitor +remote hosts on the other side of the firewall. +This assumes the firewall has been configured +with a compliant +.B sockd +daemon and the necessary access controls are satisfied. +.SH "CONFIGURATION" +.B pmsocks +uses the +.BR tsocks (5) +library, which is not included with PCP. +You can get +.B tsocks +from +.IR http://www.progsoc.uts.edu.au/~delius/ . +.SH "IRIX CONFIGURATION" +On IRIX, +.B pmsocks +is simply a shell wrapper that sets the appropriate environment variables +and then executes the +.I path +program with +.I args +arguments (if any). +.B pmsocks +works by setting the +.B _RLD_LIST +environment variable (see +.BR rld (1)) +to load a dynamic shared library (see +.BR dso (5)) +containing stubs for ``socksified'' network library functions; +This ``socksified'' library is installed at +.IR /usr/pcp/lib/libpcp_socks.so . +.PP +There are a number of conditions required for this +to be successful and the user is strongly advised to +read this whole manual page (in particular the +.B CAVEAT +section below) before attempting to use +.BR pmsocks . +.PP +When +.B pmsocks +is installed, the +.I /etc/pcp_socks.conf +configuration file is also installed with +minimum default settings. +These settings specify that socket connections to the +local host should be made directly, without +contacting any socks server daemon. +This is necessary so that PCP clients +will be able to establish a local connection to the +.BR X (1) +server, +and use PCP connections, possibly via a +.B sockd +daemon, to monitor remote hosts. +In the present implementation of +.BR pmsocks , +non-direct connections to the +.BR X (1) +server do not work, hence if the +display is remote, then the remote host must be on the same side of the +firewall and +.I /etc/pcp_socks.conf +must be configured to connect directly to that host. +.PP +The format of +.I /etc/pcp_socks.conf +is identical to +.IR /etc/socks.conf +as documented in the +.I "CSTC-4.2" +socks distribution. +This distribution may be obtained via +information contained in the socks FAQ at +.ce 1 +ftp://coast.cs.purdue.edu/pub/tools/unix/socks/ +.PP +If other socks clients are being used, then it is +generally safe to remove +.I /etc/pcp_socks.conf +and instead make a symbolic link to +.IR /etc/socks.conf . +The file formats are identical. +.PP +The default configuration should be customized to suit the +local environment so that connections to hosts +located on the same side of the firewall as the local host +do not use the socks daemon unnecessarily. +The default configuration +is +.sp 1 +.in 1i +direct LOCALHOSTNAME 255.255.255.255 # direct localhost +.br +sockd 0.0.0.0 0.0.0.0 # contact sockd everywhere else +.in +.sp 1 +Note that the string +.B LOCALHOSTNAME +is dynamically substituted at run time with the name of the local host, +as obtained by a call to +.BR gethostname (2). +Assuming the real IP address of the local host is +.B 1.2.3.4 +and that a normal class-c subnet is used locally, +the most common customization would be to +specify direct connections for all hosts on the +local subnet, by inserting another ``direct'' line as follows: +.sp 1 +.in 1i +direct LOCALHOSTNAME 255.255.255.255 # direct localhost +.br +direct 1.2.3.0 255.255.255.0 # direct on local subnet +.br +sockd 0.0.0.0 0.0.0.0 # contact sockd everywhere else +.in +.PP +The order of lines is important \- the first line +matching the requested destination IP address during a +.BR connect (2) +call (after the requested IP address has been +masked by the third parameter of the +.IR /etc/pcp_socks.conf +line), +specifies via the first parameter whether to contact the socks daemon +or whether to attempt a direct connection. +.SH "IRIX ENVIRONMENT VARIABLES" +There are several environment variables used by +.B pmsocks +as follows: +.TP 10 +.B SOCKS_SERVER +Specifies the host name or IP address of the host +running the +.B sockd +daemon. +Usually this is the name of the firewall host. +.TP 10 +.B SOCKS_PORT +The TCP/IP port to use when contacting +.B sockd +on the +.B SOCKS_SERVER +host. +The default is +.BR 1080 . +.TP 10 +.B SOCKS_NS +The host name of the name server to use, +usually to resolve the IP address of +.BR SOCKS_SERVER . +.TP 10 +.B SOCKS_DEBUG +If present in the environment, +.B libpcp_socks +will print debugging information to the +.I stderr +stream. +There are only two levels of debugging, on or off. +This is only really useful for the developers +because the debugging information assumes +knowledge of the +.B libpcp_socks +source code. +.TP 10 +.B SOCKS_BANNER +If this is set, whenever a client calls +.B libpcp_socks +it will echo a message to +.I stdout +containing version information. +This can be useful to check +.B libpcp_socks +is working in the absence of verbose logging. +.TP 10 +.B _RLD_LIST +.B pmsocks +sets this to exactly +.B /usr/pcp/lib/libpcp_socks.so:DEFAULT +.br +It is strongly recommended this NOT be set +in the environment of interactive shells. +.TP 10 +.B PMCD_CONNECT_TIMEOUT +Specifies the time-out, in seconds, for connections to +.BR pmcd (1). +When using +.BR pmsocks , +this may need to be increased from the default (5 seconds) +due to the additional delays introduced as a result of using +.BR sockd . +See +.BR PMAPI (3) +for further details about this variable. +.SH CAVEAT +The following notes should be considered carefully: +.TP 5 +0) +Because +.B sockd +can only handle TCP/IP sockets, +.B pmsocks +never attempts to use +.B sockd +for sockets of type +.B SOCK_DGRAM +or if the +.B domain +parameter in a call to +.BR socket (2) +is +.B PF_UNIX +(unix domain sockets should never need to use +.B sockd +anyway). +.TP 5 +1) +Some firewall products do not support ``socksified'' applications, +and in these cases, +.B pmsocks +cannot be used. +In this case, it will be necessary to configure the firewall to allow +connections through the firewall for the PMCD communications port, +typically tcp/4321. +.TP 5 +2) +The PCP protocol is TPC/IP-based and works with the socks protocol, +but connections which use UDP/DATAGRAM sockets +or remote X11 connections via +.B sockd +may not work. +If the remote display host is on the same side of the firewall +as the application, this may be circumvented by configuring +the remote display host to use direct connections - see above. +Also, using X11 display options which use shared memory may hang +the X server when used with +.BR pmsocks . +.TP 5 +3) +If the +.B pmsocks +configuration file is not present, then +.B pmsocks +will exit with an error message. +.TP 5 +4) +.B pmsocks +uses the locally configured name server or resolver +(see +.BR resolver (5)) +to resolve host names to IP addresses. +This may or may not be capable of resolving host names +on the other side of the firewall. +.TP 5 +5) +When used over a WAN, often the +.B sockd +daemon will be a long way from the application. +This may result in PCP client connections timing out before +connecting to the remote +.BR pmcd . +If this is occurring, set the environment variable +.B PMCD_CONNECT_TIMEOUT +to a higher value than the default (5 seconds). +Refer to +.BR PMAPI (3) +for further details about this variable. +.TP 5 +6) +When using +.B pmsocks +to connect to +.BR pmcd (1), +but +.I "``Connection Refused''" +error messages are returned, +it is not immediately obvious whether +.BR pmcd (1) +is returning the error or +.BR sockd . +.SH "COPYRIGHT NOTICE" +.B tsocks +is covered by the GPL license and is copyright +Shaun Clowes (delius@progsoc.org). +.SH "FILES" +.TP 10 +.B /etc/tsocks.conf +configuration file +.SH "SEE ALSO" +.BR pmcd (1), +.BR pminfo (1), +.BR pmlogger (1), +.BR pmval (1), +.BR X (1), +.BR PMAPI (3), +.BR resolver (5), +and +.BR tsocks (5). diff --git a/man/man1/pmstat.1 b/man/man1/pmstat.1 new file mode 100644 index 0000000..2bac73b --- /dev/null +++ b/man/man1/pmstat.1 @@ -0,0 +1,325 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMSTAT 1 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmstat\f1 \- high-level system performance overview +.\" literals use .B or \f3 +.\" arguments use .I or \f2 +.SH SYNOPSIS +\f3pmstat\f1 +[\f3\-gLlPxz\f1] +[\f3\-A\f1 \f2align\f1] +[\f3\-a\f1 \f2archive\f1] +[\f3\-h\f1 \f2host\f1] +[\f3\-H\f1 \f2file\f1] +[\f3\-n\f1 \f2pmnsfile\f1] +[\f3\-O\f1 \f2offset\f1] +[\f3\-p\f1 \f2port\f1] +[\f3\-S\f1 \f2starttime\f1] +[\f3\-s\f1 \f2samples\f1] +[\f3\-T\f1 \f2endtime\f1] +[\f3\-t\f1 \f2interval\f1] +[\f3\-Z\f1 \f2timezone\f1] +.SH DESCRIPTION +.B pmstat +provides a one line summary of system performance every +.I interval +unit of time (the default is 5 seconds). +.B pmstat +is intended to monitor system performance at the highest level, +after which other tools may be used to examine subsystems in which +potential performance problems may be observed in greater detail. +.P +Multiple hosts may be monitored by supplying more than +one host with multiple +.B \-h +flags (for live monitoring) or by providing a name of the hostlist file, where +each line contain one host name, with +.B \-H, +or multiple +.B \-a +flags (for retrospective monitoring from an archive). +.P +The +.B \-t +option may be used to change the default reporting +.IR interval . +The +.I interval +argument follows the syntax described in +.BR PCPIntro (1), +and in the simplest form may be an unsigned integer (the implied +units in this case are seconds). +.PP +By default, +.B pmstat +fetches metrics by connecting to the Performance Metrics Collector +Daemon (PMCD) on the local host. If the +.B \-L +option is specified, then +.BR pmcd (1) +is bypassed, and metrics are fetched from PMDAs on the local host +using the standalone +.B PM_CONTEXT_LOCAL +variant of +.BR pmNewContext (3). +When the +.B \-h +option is specified, +.B pmstat +connects to the +.BR pmcd (1) +on +.I host +and fetches metrics from there. +As mentioned above, multiple hosts may be monitored +by supplying multiple +.B \-h +flags. +.PP +Alternatively, if the +.B \-a +option is used, the metrics are retrieved from the Performance Co-Pilot +archive log files identified by the base name +.IR archive . +Multiple archives may be replayed by supplying multiple +.B \-a +flags. +When the +.B \-a +flag is used, +the +.B \-P +flag may also be used to pause the output after each interval. +.PP +Standalone mode can only connect to the local host, using an archive implies +a host name, and nominating a host precludes using an archive, so the options +.BR \-L , +.B \-a +and +.B \-h +are mutually exclusive. +.PP +Normally +.B pmstat +operates on the default Performance Metrics Name Space (PMNS), however +if the +.B \-n +option is specified an alternative namespace is loaded +from the file +.IR pmnsfile . +.PP +If the +.B \-s +the option is specified, +.I samples +defines the number of samples to be retrieved and reported. +If +.I samples +is 0 or +.B \-s +is not specified, +.B pmstat +will sample and report continuously \- this is the default behavior. +.PP +When processing an archive, +.B pmstat +may relinquish its own timing control, and operate as a ``slave'' of a +.BR pmtime (1) +process that uses a GUI dialog to provide timing control. +In this case, either the +.B \-g +option should be used to start +.B pmstat +as the sole slave of a new +.BR pmtime (1) +instance, or +.B \-p +should be used to attach +.B pmstat +to an existing +.BR pmtime (1) +instance via the IPC channel identified by the port argument. +.PP +The +.BR \-S , +.BR \-T , +.BR \-O +and +.B \-A +options may be used to define a time window to restrict the +samples retrieved, set an initial origin within the time window, +or specify a ``natural'' alignment of the sample times; refer to +.BR PCPIntro (1) +for a complete description of these options. +.PP +The +.B \-l +option prints the last 7 characters of a hostname in summaries involving +more than one host (when more than one +.B \-h +option has been specified on the command line). +.PP +The +.B \-x +option (extended CPU metrics) causes two additional CPU metrics to be +reported, namely wait for I/O ("wa") and virtualisation steal time ("st"). +.PP +The output from +.B pmstat +is directed to standard output, and the columns +in the report are interpreted as follows: +.PP +.TP 10 +.B loadavg +The +.I "1 minute" +load average. +.TP +.B memory +The \f3swpd\fP column indicates average swap space used during the interval, +in Kbytes. +The \f3free\fP column indicates average free memory during the interval, +in Kbytes. +The \f3buff\fP column indicates average buffer memory in use during the interval, +in Kbytes. +The \f3cache\fP column indicates average cached memory in use during the interval, +in Kbytes. +.RS +.PP +If the values become large, they are reported as Mbytes +.BR "" ( m " suffix)" +or Gbytes +.BR "" ( g " suffix)." +.RE +.TP +.B swap +The metrics in this area of the kernel instrumentation are of +varying value. We try to report the average number of \f3pages\fP +that are paged in (\f3pi\fP) and out (\f3po\fP) per second during +the interval. +If the corresponding page swapping metrics are unavailable, we report +the average rate per second +of swap \f3operations\fP in (\f3si\fP) and out (\f3so\fP) during the interval. +It is normal for the ``in'' values to be non-zero, but the system +is suffering memory stress if the ``out'' values are non-zero over +an extended period. +.RS +.PP +If the values become large, they are reported as thousands of +operations per second +.BR "" ( K " suffix)" +or millions of operations per second +.BR "" ( M " suffix)." +.RE +.TP +.B io +The \f3bi\fP and \f3bo\fP columns indicate the average rate per second +of block input and block output operations (respectfully) during the interval. +Unless all file systems have a 1 Kbyte block size, these +rates do not directly indicate Kbytes transferred. +.RS +.PP +If the values become large, they are reported as thousands of +operations per second +.BR "" ( K " suffix)" +or millions of operations per second +.BR "" ( M " suffix)." +.RE +.TP +.B system +Interrupt rate (\f3in\fP) and +context switch rate (\f3cs\fP). +Rates are expressed as average operations per second during the interval. +Note that the interrupt rate is normally at least +.I HZ +(the clock interrupt rate, usually 100) +interrupts per second. +.RS +.PP +If the values become large, they are reported as thousands of +operations per second +.BR "" ( K " suffix)" +or millions of operations per second +.BR "" ( M " suffix)." +.RE +.TP +.B cpu +Percentage of CPU time spent executing user and "nice user" code (\f3us\fP), +system and interrupt processing code (\f3sy\fP), idle loop (\f3id\fP). +.P +If any values for the associated performance metrics are unavailable, +the value appears as ``?'' in the output. +.PP +By default, +.B pmstat +reports the time of day according to the local timezone on the +system where +.B pmstat +is run. +The +.B \-Z +option changes the timezone to +.I timezone +in the format of the environment variable +.B TZ +as described in +.BR environ (5). +The +.B \-z +option changes the timezone to the local timezone at the +host that is the source of the performance metrics, as identified via +either the +.B \-h +or +.B \-a +options. +.SH FILES +.PD 0 +.TP 10 +.BI $PCP_VAR_DIR/pmns/ * +default PMNS specification files +.TP +.BI $PCP_SYSCONF_DIR/pmlogger/config.pmstat +.BR pmlogger (1) +configuration for creating an archive suitable for replay with +.B pmstat +.PD +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.I /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). +.SH SEE ALSO +.BR PCPIntro (1), +.BR pmclient (1), +.BR pmtime (1), +.BR PMAPI (3), +.BR pmNewContext (3), +.BR pcp.conf (5) +and +.BR pcp.env (5). +.SH DIAGNOSTICS +All are generated on standard error, and are intended to be self-explanatory. diff --git a/man/man1/pmstore.1 b/man/man1/pmstore.1 new file mode 100644 index 0000000..1457f7a --- /dev/null +++ b/man/man1/pmstore.1 @@ -0,0 +1,166 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000-2004 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMSTORE 1 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmstore\f1 \- modify performance metric values +.\" literals use .B or \f3 +.\" arguments use .I or \f2 +.SH SYNOPSIS +\f3pmstore\f1 +[\f3\-L\f1] +[\f3\-h\f1 \f2host\f1] +[\f3\-i\f1 \f2instances\f1] +[\f3\-K\f1 \f2spec\f1] +[\f3\-n\f1 \f2pmnsfile\f1] +\f2metricname\f1 \f2value\f1 +.SH DESCRIPTION +Under certain circumstances, it is useful to be able to modify the values +of performance metrics, for example to re-initialize counters or to assign +new values to metrics that act as control variables. +.PP +.B pmstore +changes the current values for the nominated instances of a +single performance metric, as identified by +.I metricname +and the list of instance identifiers following the +.B \-i +argument. +.I instances +must be a single argument, with +elements of the list separated by commas and/or white space. +By default all +instances of +.I metricname +will be updated. +.PP +Normally +.B pmstore +operates on the default Performance Metrics Name Space (PMNS), however +if the +.B \-n +option is specified an alternative namespace is loaded +from the file +.IR pmnsfile. +.PP +Unless directed to another host by the +.B \-h +option, +.B pmstore +will interact with the Performance Metric Collector Daemon (PMCD) +on the local host. +.PP +The +.B \-L +option causes +.B pmstore +to use a local context to store to metrics from PMDAs on the local host +without PMCD. Only some metrics are available in this mode. +The +.BR \-h +and +.B \-L +options are mutually exclusive. +.PP +The interpretation of +.I value +is dependent on the syntax used in its specification and +the underlying data type of +.IR metricname , +as follows. +.IP 1. 4 +If the metric has an \fBinteger\fR type, then +.I value +should be an optional leading hyphen, followed either by decimal digits +or ``0x'' and some hexadecimal digits. ``0X'' is also acceptable in lieu +of ``0x''. +See +.BR strtol (3C) +and the related routines. +.IP 2. 4 +If the metric has a \fBfloating point\fR type, then +.I value +should be either in the form of an integer described above, or +a fixed point number, or a number in scientific notation. +See +.BR strtod (3C). +.IP 3. 4 +If the metric has a \fBstring\fR type, then +.I value +is interpreted as a literal string of ASCII characters. +.IP 4. 4 +If the metric has any other type (i.e. +.B PM_TYPE_EVENT +or +.BR PM_TYPE_AGGREGATE ) +then no encoding of +.I value +from the command line makes sense, and the values of these metrics cannot +be modified with +.BR pmstore . +.PP +The output reports the old value and the new value for each updated +instance of the requested metric. +.PP +When using the +.B \-L +option to fetch metrics from a local context, the +.B \-K +option may be used to control the DSO PMDAs that should be +made accessible. The +.I spec +argument conforms to the syntax described in +.BR __pmSpecLocalPMDA (3). +More than one +.B \-K +option may be used. +.SH FILES +.PD 0 +.TP 10 +.BI $PCP_VAR_DIR/pmns/ * +default PMNS specification files +.PD +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.I /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). +.SH SEE ALSO +.BR pmcd (1), +.BR pminfo (1), +.BR pmval (1), +.BR __pmSpecLocalPMDA (3), +.BR strtod (3) +and +.BR strtol (3). +.SH DIAGNOSTICS +Two messages indicate a mismatch between the internal data type for +.I metricname +and the +.I value +provided. +.P +The value "???" is out of range for the data type (PM_TYPE_...) +.P +The value "???" is incompatible with the data type (PM_TYPE_...) diff --git a/man/man1/pmtime.1 b/man/man1/pmtime.1 new file mode 100644 index 0000000..6a2af1f --- /dev/null +++ b/man/man1/pmtime.1 @@ -0,0 +1,66 @@ +.TH PMTIME 1 "" "Performance Co-Pilot" +.SH NAME +\f3pmtime\f1 \- time control server for Performance Co-Pilot +.SH SYNOPSIS +\f3pmtime\f1 +[\f3\-p\f1 \f2port\f1] +.SH DESCRIPTION +.B pmtime +is a graphical user interface for performance monitoring applications +using the PCP infrastructure and requiring interactive time control. +.PP +.B pmtime +is not normally invoked directly by users. +Rather, it is more typical for it to be started by client applications +(e.g. +.BR pmchart (1) +and +.BR pmval (1)). +.PP +There are two modes of interacting with a +.B pmtime +process - live host mode, and historical archive mode. +In archive mode the window presents time controls suitable for +manipulating the archive position, allowing full VCR control to +move forwards and backwards in time at configurable rates and +intervals. +In live mode the +.B pmtime +window contains the simpler time controls suitable for +live monitoring. +.PP +The arguments to +.B pmtime +are as follows: +.TP 5 +.B \-p +.I port +is the port number which +.B pmtime +will use for communication with its clients (monitoring applications). +.PP +Note that the +.B pmtime +window is only made visible when explicitly requested. +Multiple client applications can be connected to a single +.B pmtime +server \- when the final client application exits, +.B pmtime +will also exit. +.SH ENVIRONMENT +When a port number is not explicitly requested on the command line +via the +.B \-p +option, the environment variable +.I PMTIME_PORT +can be set to specify the port number from which available-port +probing will commence when +.B pmtime +is searching for a port number to use. +.PP +The default starting port number is 43334. +.SH SEE ALSO +.BR PCPIntro (1), +.BR pmchart (1), +and +.BR pmval (1). diff --git a/man/man1/pmtrace.1 b/man/man1/pmtrace.1 new file mode 100644 index 0000000..114f2e1 --- /dev/null +++ b/man/man1/pmtrace.1 @@ -0,0 +1,126 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000-2004 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMTRACE 1 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmtrace\f1 \- command line performance instrumentation +.\" literals use .B or \f3 +.\" arguments use .I or \f2 +.SH SYNOPSIS +\f3pmtrace\f1 +[\f3-q\f1] +[\f3\-c\f1 \f2value\f1 | \f3\-e\f1 \f2command\f1 | \f3\-v\f1 \f2value\f1] +[\f3\-h\f1 \f2host\f1] +[\f3\-S\f1 \f2state\f1] +\f2tag\f1 +.SH DESCRIPTION +.B pmtrace +provides a simple command line interface to the trace Performance Metrics Domain +Agent (PMDA) and the associated \f2pcp_trace\f1 library. +.PP +The default +.B pmtrace +behavior is to provide point trace data to the trace PMDA, using the +.I tag +argument as the identifying name associated with each trace point. +The +.I tag +then becomes an instance identifier within the set of trace.point metrics. +.PP +The +.B \-e +option allows an arbitrary \f2command\f1 to be executed. +This \f2command\f1 will be measured as a transaction since it has well defined +start and end points. The information is made available through the +trace.transact metrics. +.PP +Trace data can be sent to the trace PMDA running on +.IR host , +rather than the localhost, using +the +.B \-h +option. +This overrides use of the environment variable +.BR PCP_TRACE_HOST . +.PP +The +.B \-q +option suppresses messages from a successful trace, so that +.B pmtrace +runs quietly. +.PP +The +.B \-c +option allows an arbitrary counter \f2value\f1 to be exported through +the trace.count metrics, while the +.B \-v +option allows an arbitrary floating point \f2value\f1 to be exported through +the trace.observe metrics +.PP +The +.B \-S +option enables internal debugging and tracing. The value of +.I state +is a bit-wise combination of debug flags as defined in +.BR pmtracestate (3), +and may be specified using the decimal or hexadecimal syntax prescribed +by +.BR strtol (3). +.PP +.SH ENVIRONMENT +Since +.B pmtrace +uses the \f2libpcp_trace\f1 library routines, the environment variables +\f3PCP_TRACE_HOST\f1, \f3PCP_TRACE_PORT\f1, and \f3PCP_TRACE_TIMEOUT\f1 +are all honored. +Refer to +.BR pmdatrace (3) +for a detailed description of the semantics of each. +.SH FILES +.PD 0 +.TP 10 +.BI $PCP_DEMOS_DIR/trace/pmtrace.c +source code for +.B pmtrace +.PD +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.I /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). +.SH SEE ALSO +.BR pmcd (1), +.BR pmdatrace (1), +.BR pmprobe (1), +.BR PMAPI (3), +and +.BR pmdatrace (3). +.SH DIAGNOSTICS +All are generated on standard error and are intended to be self-explanatory. +.PP +The +.B pmtrace +exit status is always zero except when the +.B \-e +option is in use, in which case the exit status of \f2command\f1 is returned. diff --git a/man/man1/pmval.1 b/man/man1/pmval.1 new file mode 100644 index 0000000..7f06b36 --- /dev/null +++ b/man/man1/pmval.1 @@ -0,0 +1,411 @@ +'\"! tbl | mmdoc +'\"macro stdmacro +.\" +.\" Copyright (c) 2000 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMVAL 1 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmval\f1 \- performance metrics value dumper +.\" literals use .B or \f3 +.\" arguments use .I or \f2 +.SH SYNOPSIS +\f3pmval\f1 +[\f3\-dgrz\f1] +[\f3\-A\f1 \f2align\f1] +[\f3\-a\f1 \f2archive\f1] +[\f3\-f\f1 \f2N\f1] +[\f3\-h\f1 \f2host\f1] +[\f3\-i\f1 \f2instances\f1] +[\f3\-K\f1 \f2spec\f1] +[\f3\-n\f1 \f2pmnsfile\f1] +[\f3\-O\f1 \f2offset\f1] +[\f3\-p\f1 \f2port\f1] +[\f3\-S\f1 \f2starttime\f1] +[\f3\-s\f1 \f2samples\f1] +[\f3\-T\f1 \f2endtime\f1] +[\f3\-t\f1 \f2interval\f1] +[\f3\-U\f1 \f2archive\f1] +[\f3\-w\f1 \f2width\f1] +[\f3\-Z\f1 \f2timezone\f1] +\f2metricname\f1 +.SH DESCRIPTION +.de EX +.in +0.5i +.ie t .ft CB +.el .ft B +.ie t .sp .5v +.el .sp +.ta \\w' 'u*8 +.nf +.. +.de EE +.fi +.ie t .sp .5v +.el .sp +.ft R +.in +.. +.B pmval +prints current or archived values for the nominated performance metric. +The metric of interest is named in the +.I metricname +argument, subject to instance qualification with the +.B \-i +flag as described below. +.PP +Unless directed to another host by the +.B \-h +option, +or to an archive by the +.B \-a +or +.B \-U +options, +.B pmval +will contact the Performance Metrics Collector Daemon (PMCD) +on the local host to obtain the required information. +.PP +The +.I metricname +argument may also be given in the metric specification syntax, as +described in +.BR PCPIntro (1), +where the source, metric and instance may all be included in the +.IR metricname , +e.g. thathost:kernel.all.load["1 minute"]. +When this format is used, none of the +.B \-h +or +.B \-a +or +.B \-U +options may be specified. +.PP +When using the metric specification syntax, the ``hostname'' +.B @ +is treated specially and +causes +.B pmval +to use a local context to collect metrics from PMDAs on the local host +without PMCD. Only some metrics are available in this mode. +.PP +When processing an archive, +.B pmval +may relinquish its own timing control, and operate as a ``slave'' of +a +.BR pmtime (1) +process that uses a GUI dialog to provide timing control. +In this case, either the +.B \-g +option should be used to start +.B pmval +as the sole slave of a new +.BR pmtime (1) +instance, or +.B \-p +should be used to attach +.B pmval +to an existing +.BR pmtime (1) +instance via the IPC channel identified by the +.I port +argument. +.PP +The +.BR \-S , +.BR \-T , +.BR \-O +and +.B \-A +options may be used to define a time window to restrict the +samples retrieved, set an initial origin within the time window, +or specify a ``natural'' alignment of the sample times; refer to +.BR PCPIntro (1) +for a complete description of these options. +.PP +The other options which control the source, timing and layout of the information +reported by +.B pmval +are as follows: +.TP 5 +.B \-a +Performance metric values are retrieved from the Performance Co-Pilot (PCP) +archive log file identified by the base name +.IR archive . +.TP +.B \-d +When replaying from an archive, +this option requests that the prevailing real-time delay be applied between +samples (see +.BR \-t ) +to effect a pause, rather than the default behaviour of replaying at full speed. +.TP +.B \-f +Numbers are reported in ``fixed point'' notation, rather than the default +scientific notation. Each number will be up to the column width determined by +the default heuristics, else the +.B \-w +option if specified, and include +.I N +digits after the decimal point. So, the options +.B "\-f 3 \-w 8" +would produce numbers of the form 9999.999. +A value of zero for +.I N +omits the decimal point and any fractional digits. +.TP +.B \-g +Start +.B pmval +as the slave of a new +.BR pmtime (1) +process for replay of archived performance data using the +.BR pmtime (1) +graphical user interface. +.TP +.B \-h +Current performance metric values are retrieved from the nominated +.I host +machine. +.TP +.B \-i +.I instances +is a list of one or more +instance names for the nominated performance metric \- just these +instances will be retrieved and reported +(the default is to report all instances). +The list must be a single argument, with +elements of the list separated by commas and/or white space. +.RS +.PP +The instance name may be quoted with single (') or double (") quotes +for those cases where +the instance name contains white space or commas. +.PP +Multiple +.B \-i +options are allowed as an alternative way of specifying more than +one instance of interest. +.PP +As an example, the following are all equivalent: +.EX +$ pmval \-i "'1 minute','5 minute'" kernel.all.load +$ pmval \-i '"1 minute","5 minute"' kernel.all.load +$ pmval \-i "'1 minute' '5 minute'" kernel.all.load +$ pmval \-i "'1 minute'" \-i "'5 minute'" kernel.all.load +$ pmval 'localhost:kernel.all.load["1 minute","5 minute"]' +.EE +.RE +.TP +.B \-K +When +fetching metrics from a local context, the +.B \-K +option may be used to control the DSO PMDAs that should be +made accessible. The +.I spec +argument conforms to the syntax described in +.BR __pmSpecLocalPMDA (3). +More than one +.B \-K +option may be used. +.TP +.B \-n +Normally +.B pmval +operates on the default Performance Metrics Name Space (PMNS), however +if the +.B \-n +option is specified an alternative namespace is loaded +from the file +.IR pmnsfile. +.TP +.B \-p +Attach +.B pmval +to an existing +.BR pmtime (1) +time control process instance via the IPC channel identified by the +\f2port\f1 argument. +This option is normally only used by other tools, e.g. +.BR pmchart (1), +when they launch +.B pmval +with synchronized time control. +.TP +.B \-r +Print raw values for cumulative counter metrics. Normally cumulative counter +metrics are converted to rates. For example, disk transfers are reported +as number of disk transfers per second during the preceding sample interval, +rather than the raw value of number of disk transfers since the machine was +booted. If you specify this option, the raw metric values are printed. +.TP +.B \-s +The argument +.I samples +defines the number of samples to be retrieved and reported. +If +.I samples +is 0 or +.B \-s +is not specified, +.B pmval +will sample and report continuously (in real time mode) or until the end +of the PCP archive (in archive mode). +.TP +.B \-t +The default update \f2interval\f1 may be set to something other than the +default 1 second. +The +.I interval +argument follows the syntax described in +.BR PCPIntro (1), +and in the simplest form may be an unsigned integer (the implied +units in this case are seconds). +.TP +.B \-U +Performance metric values are retrieved from the Performance Co-Pilot (PCP) +archive log file identified by the base name +.IR archive , +although unlike +.B \-a +every recorded value in the archive for the selected metric +and instances is reported (so no interpolation mode, and the sample +interval (\c +.B \-t +option) is ignored. +.RS +5n +.PP +At most one of the options +.B \-a +and +.B \-U +may be specified. +.RE +.TP +.B \-w +Set the width of each column of output to be +.I width +columns. +If not specified columns are wide +enough to accommodate the largest value of the type being printed. +.TP +.B \-Z +By default, +.B pmval +reports the time of day according to the local timezone on the +system where +.B pmval +is run. +The +.B \-Z +option changes the timezone to +.I timezone +in the format of the environment variable +.B TZ +as described in +.BR environ (5). +.TP +.B \-z +Change the reporting timezone to the local timezone at the host that is +the source of the performance metrics, as identified via either the +.I metricname +or the +.B \-h +or +.B \-a +or +.B \-U +options. +.PP +The following symbols may occasionally appear, in place of a metric value, in +.B pmval +output: A question mark symbol (?) indicates that a value is no +longer available for that metric instance. An exclamation mark (!) +indicates that a 64-bit counter wrapped during the sample. +.PP +The output from +.B pmval +is directed to standard output. +.SH FILES +.PD 0 +.TP 10 +.BI $PCP_VAR_DIR/pmns/ * +default PMNS specification files +.PD +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.I /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). +.SH SEE ALSO +.BR PCPIntro (1), +.BR pmcd (1), +.BR pmchart (1), +.BR pmdumplog (1), +.BR pminfo (1), +.BR pmlogger (1), +.BR pmtime (1), +.BR PMAPI (3), +.BR __pmSpecLocalPMDA (3), +.BR pcp.conf (5) +and +.BR pcp.env (5). +.SH DIAGNOSTICS +All are generated on standard error and are intended to be self-explanatory. +.SH CAVEATS +By default, +.B pmval +attempts to display non-integer numeric values in a way that does not distort the +inherent precision (rarely more than 4 significant +digits), and tries to maintain a tabular format in +the output. These goals are sometimes in conflict. +.PP +In the absence of the +.B \-f +option (described above), +the following table describes the formats used for different +ranges of numeric values for any metric that is of type +.B PM_TYPE_FLOAT +or +.BR PM_TYPE_DOUBLE , +or any metric that has the semantics of a counter (for +which +.B pmval +reports the rate converted value): +.TS +box,center; +cf(R) | cf(R) +rf(CW) | lf(R). +Format Value Range +_ +! No values available +9.999E-99 < 0.1 +0.0\0\0\0 0 +9.9999 > 0 and <= 0.9999 +9.999\0 > 0.9999 and < 9.999 +99.99\0\0 > 9.999 and < 99.99 +999.9\0\0\0 > 99.99 and < 999.9 +9999.\0\0\0\0 > 999.9 and < 9999 +9.999E+99 > 9999 +.TE diff --git a/man/man1/pmview.1 b/man/man1/pmview.1 new file mode 100644 index 0000000..3f0ceb7 --- /dev/null +++ b/man/man1/pmview.1 @@ -0,0 +1,590 @@ +.TH PMVIEW 1 "" "Performance Co-Pilot" +.SH NAME +\f3pmview\f1 \- performance metrics 3D visualization back-end +.SH SYNOPSIS +\f3pmview\f1 +[\f3\-Cz\f1] +[\f3\-A\f1 \f2align\f1] +[\f3\-a\f1 \f2archive\f1[\f3,\f2archive\f3,\f1...]] +[\f3\-c\f1 \f2configfile\f1] +[\f3\-h\f1 \f2host\f1] +[\f3\-n\f1 \f2pmnsfile\f1] +[\f3\-O\f1 \f2origin\f1] +[\f3\-p\f1 \f2port\f1] +[\f3\-R\f1 \f2logconfig\f1] +[\f3\-r\f1 \f2addconfig\f1] +[\f3\-S\f1 \f2starttime\f1] +[\f3\-t\f1 \f2interval\f1] +[\f3\-T\f1 \f2endtime\f1] +[\f3\-x\f1 \f2version\f1] +[\f3\-Z\f1 \f2timezone\f1] +[\f3\-geometry\f1 \f2geometry\f1] +[\f3\-display\f1 \f2display\f1] +[\f3\-name\f1 \f2name\f1] +[\f3\-title\f1 \f2title\f1] +[\f3\-xrm "\f1\f2resourceName\f1\f3:\f2 value\f3"\f1 ...] +[\f2other X11-args\f1] +.SH DESCRIPTION +.B pmview +is a +generalized 3D performance metrics visualization tool for the +Performance Co-Pilot +.RB ( PCP (1)). +.PP +.B pmview +is the base utility behind performance metrics visualization tools such as +.BR dkvis (1), +.BR mpvis (1), +.BR osvis (1) +and +.BR nfsvis (1), +It is also used by a range of related tools that are specific to optional +Performance Domain Agents +(PMDA) +and/or PCP add-on products. +.B pmview +may also be used to construct customized 3D performance displays. +.PP +.B pmview +displays performance metrics as colored blocks and cylinders arranged +on monochrome base planes. Each object may represent a single performance +metric, or a stack of several performance metrics. Since the objects +are modulated by the value of the metric they represent, only +numerical metrics may be visualized. Objects representing a single +metric may be modulated in terms of height, color, or height and +color. Objects in a stack may only be height modulated, but the stack +can be normalized to the maximum height. Labels may be added to the +scene to help identify groups of metrics. +.PP +A configuration file (as specified by the +.B \-c +option, or read from standard input) is used to specify the position, +color, maximum value and labels of metrics and metric instances in the +scene. The maximum value acts as a normalization factor and is used +to scale the object height and/or color in proportion to the metric +values. Metric values which exceed the associated maximum value are +displayed as solid white objects. If a metric is unavailable, the +object will have minimum height and will be colored grey. +.PP +Normally, the tool operates in ``live'' mode where performance metrics +are fetched in real-time. The user can view metrics from any host +running +.BR pmcd (1). +.B pmview +can also replay archives of performance metrics (see +.BR pmlogger (1)) +and allow the user to interactively control the current replay time and rate +using the VCR paradigm. This is particularly useful for retrospective +comparisons and for post-mortem analysis of performance problems where a remote +system is not accessible or a performance analyst is not available on-site. +.PP +All metrics in the Performance Metrics Name Space (PMNS) with numeric value +semantics from any number of hosts or archives may be visualized. +.B pmview +examines the semantics of the metrics and where sensible, converts metric +values to a rate before scaling. +.SH COMMAND LINE OPTIONS +The +.BR -S , +.BR -T , +.B -O +and +.B -A +options may be used to define a time window to restrict the samples retrieved, +set an initial origin within the time window, or specify a ``natural'' +alignment of the sample times; refer to +.BR PCPIntro(1) +for a complete description of these options. +.PP +The other available options are: +.TP +\f3-a\f1 \f2archive\f1[\f3,\f2archive\f3,\f1...]] +Specify an +.I archive +from which metrics can be obtained for a particular host. +.I archive +is the basename of an archive, previously created by +.BR pmlogger (1). +Multiple archives (separated by commas or in different \f3\-a\f1 options) +from different hosts may be given, but an error will occur if there is more +than one archive from the same host. Any metrics that are not associated with a +specific host or archive in the configuration file will use the first archive +as their source. +.TP +.B \-C +Parse the configuration file and exit before displaying the +.B pmview +window. Any errors in the configuration file are displayed. +.TP +\f3\-c\f1 \f2configfile\f1 +Load the configuration from +.I configfile +rather than standard input. +.TP +\f3\-h\f1 \f2host\f1 +Fetch performance metrics from +.BR pmcd (1) +on +.IR host , +rather than the default localhost. Implies that +.B pmview +will run in live mode, so no archives can be specified on the command line or +in the configuration file. Only one +.B \-h +option may be given. +.TP +\f3\-n\f1 \f2pmnsfile\f1 +Normally +.B pmview +operates on the distributed Performance Metrics Name Space (PMNS), however if +the +.B \-n +option is specified an alternative local PMNS is loaded from the file +.IR pmnsfile . +.TP +\f3\-p\f1 \f2port\f1 +Connect to the time controls (see +.BR pmtime (1)) +on this +.BR port . +Used when a tool launches another tool so that they can connect to the +same time controls. +.TP +\f3\-R\f1 \f2logconfig\f1 +Use +.I logconfig +as the +.BR pmlogger (1) +config when recording. +.TP +\f3\-r\f1 \f2addconfig\f1 +Append +.I addconfig +onto the +.BR pmlogger (1) +config generated by +.B pmview +when recording. +.TP +\f3\-t\f1 \f2interval\f1 +The update +.I interval +used to fetch metrics from the live or archive sources. +The +.I interval +argument follows the syntax described in +.BR PCPIntro (1), +and in the simplest form may be an unsigned integer (the implied +units in this case are seconds). +The default is 2.0 seconds. +.TP +\f3\-x\f1 \f2version\f1 +Use the specified +.I version +of the +.BR pmlaunch (5) +specification. The versions currently supported are ``1.0'' and the default +version ``2.0''. +.TP +\f3\-Z\f1 \f2timezone\f1 +By default, +.B pmview +reports the time of day according to the local timezone on the system where +.B pmview +is run. The +.B \-Z +option changes the default timezone to +.I timezone +which should be in the format of the environment variable +.B TZ +as described in +.BR environ (5). +.TP +\f3\-z\f1 +Change the reporting timezone to the local timezone at the host that is the +source of the performance metrics, as identified via either the +.B \-h +option, or the first +.B \-a +option. +.PP +\f3\-geometry\f1 \f2geometry\f1 +.br +\f3\-display\f1 \f2display\f1 +.br +\f3\-name\f1 \f2name\f1 +.br +\f3\-title\f1 \f2title\f1 +.br +\f3\-xrm\f1 \f3"\f2resourceName: value\f3"\f1 +.IP +Most standard +.BR X (1) +command line arguments may be used. +.SH WINDOW +The +.B pmview +window is comprised of a menu bar, time and scale controls, metric and time +values, and an ``examiner'' viewer (see +.BR ivview (1)), +which displays the 3D scene. +.SH EXAMINER VIEWER +The left, right and bottom edges of the examiner viewer contain a variety of +thumb wheels and buttons that can be used to adjust the visualization of the +3D scene. The +.I Rotx +and +.I Roty +thumb wheels allow the user to rotate the scene about the x and y axes, +respectively. The +.I dolly +thumb wheel moves the virtual camera closer and further from the scene allowing +the user to examine specific parts in detail or view the entire scene. On the +right edge of the viewer are eight buttons which affect the way the user can +interact with the scene. +.TP 4n +.I Pointer +Changes the cursor to a pointer which allows blocks to be selected in the +scene. See the Metric Selection section below. +.TP 4n +.I Hand +Changes the cursor to a hand which allows the scene to be rotated, translated +and dollied using a combination of mouse buttons. The left mouse button can +be used to rotate the scene in the direction of the mouse. Releasing the +left mouse button before the mouse has stopped moving will cause the scene to +continue to rotate, which can be stopped by pressing the left mouse button +again. The middle mouse button will ``pan'' the scene, and both mouse buttons +act as a dolly for the virtual camera. +.TP 4n +.I Question Mark +Displays the SGI Help information for the examiner viewer. +.TP 4n +.I Home +Changes the scene back to its original position, unless the home position has +been changed by the home pointer button. +.TP 4n +.I Home Pointer +Changes the home position of the scene to be the scene currently in view. +.TP 4n +.I Eye +Resizes the scene so that it completely fits into the 3D viewing area. +.TP 4n +.I Cross-hairs +Moves the object under the cursor to the center of the viewing area, if the +hand cursor has been selected. Pressing the ``s'' key while the cursor is +over an object has the same effect. +.TP 4n +.I Perspective Box +Switches the display between perspective and orthogonal projections. +.PP +Pressing the right mouse button within the scene window will bring up a menu +of options which affect how the 3D scene is drawn. The options include +drawing the blocks as wire frames, and turning on stereo viewing. +.SH METRIC SELECTION +When the pointer cursor is active, more information about the 3D scene can +be obtained. Text describing the metric represented by the block under the +cursor will be displayed in the top text box of the +.B pmview +window. The text contains the source and name of the metric, current value and +units, and the percentage of the expected maximum (or normalization) value. +The text box is updated whenever the scene is updated with the +latest metric values or when the cursor is moved over another block in the +scene. Moving the cursor over a base plane block, text or the surrounding +space will clear the text box. +.PP +Clicking the left mouse button on a block will bind the text box on that metric +instance so that the metric can be monitored while performing other actions +with the mouse. The block will be highlighted with a red wire frame. +Clicking the left mouse button on text or the space surrounding the scene +will unselect the object, causing the text box to revert to the original +behavior of showing the metric underneath the cursor. +.PP +Selecting a base plane instead of a modulated block will cause all the blocks +on that base plane to be selected. When more than one object is selected, the +text box behaves as if nothing is selected, so the metric displayed is the +metric currently under the cursor. Multiple selections are also possible by +pressing the SHIFT key while selecting an object with the left mouse button. +.SH MENUS +There are four menus in +.BR pmview 's +user interface which allow scenes to be recorded, saved and printed +.RB ( File ), +access to the time controls +.RB ( Options ), +launching other tools +.RB ( Launch ) +and +online help +.RB ( Help ). +.TP 4n +.B "File/Record" +When in ``live'' mode, this option will launch +.BR pmlogger (1) +processes to record the current scene into an archive folio (see +.BR pmafm(1)) +so that it may be +replayed at a later time. This option is not available in ``replay'' mode. + +When +.B "File/Record" +is selected, a file chooser dialog will prompt for the name of the new archive +folio. If the directory to the folio does not exist, +.B pmview +will attempt to create it. It is usually convenient to keep each folio within +its own directory as there will be several other files associated with the +folio, including the generated archives. + +Once a valid folio has been created, +.B pmview +will launch a +.BR pmlogger (1) +process for each host to collect the metrics required from that host in the +current scene. The current selections do not affect the set of metrics that +are recorded. + +While recording is in progress, a red dot will appear in the time controls +button in the top left-hand corner of the +.B pmview +window. The +.B "File/Record" +option will also change to +.BR "File/Stop Recording" +as only one recording session is possible at any one time. Selecting blocks or +launching other tools will have no affect on the recording session. + +The record session may be terminated by selecting +.BR "File/Stop Recording" . +This will display dialogs for each +.BR pmlogger (1) +instance describing the size and location of the archive files before +terminating each process. When all +.BR pmlogger (1) +processes have been terminated, the red dot is removed from the time controls +button, and the menu reverts back to +.B "File/Record" +to allow another recording session to take place. + +If the application exists while recording, a dialog will appear allowing you to +terminate each +.BR pmlogger (1) +process, or leave it running unattached. + +An archive folio may be replayed using the command: +.RB `` pmafm +.I folio +.BR replay ''. +See +.BR pmafm (1) +for more details. + +It is not uncommon for a front-end script which generates a +.B pmview +scene to use metrics that are not contained in the scene. For example, +.BR osvis (1) +uses several +.I hinv +metrics to determine the size and layout of some objects. As these metrics are +also needed when replaying the generated archive with the front-end script, +a complete +.BR pmlogger (1) +config can be specified +.RB ( \-R ) +that overrides the +.B pmview +generated config, or an additional config can be appended +.RB ( \-r ) +to the +.B pmview +generated config. +.TP 4n +.B "File/Save" +Saves the current scene to a human-readable Open Inventor file (see +.BR inventor (1)). +A file dialog will prompt for the location of the file. The default file +extension is ``.iv'' which is recognized by +.BR ivview (1) +and some Web browsers. +.TP 4n +.B "File/Print" +Outputs the current scene to a printer. A print dialog will be displayed +allowing a specific printer to be selected. +.TP 4n +.B "File/Quit" +.B pmview +immediately exits. If recording was active, dialogs will be displayed for +each +.BR pmlogger (1) +process so that they may be terminated. +.TP 4n +.B "Options/Show Time Control" +Displays the time controls (see +.BR pmtime (1)) +that are driving this instance of +.BR pmview . +The time controls may be shared by other tools, including +.BR pmchart (1), +that have been launched by other instances of +.B pmview +and +.BR oview (1). +Therefore, this menu item may appear to have no affect if the time controls +are already visible. +.TP 4n +.B "Options/New Time Control" +Disconnect with the current time controls (which may be shared by other tools, +see +.BR pmtime (1)) +and use a new time control that is not connected to any other tools. The new +time control will be immediately displayed. +.TP 4n +.B "Launch" +The launch menu is generated from a menu specification file (see +.BR pmlaunch (5)). +The menu contains tools that may be launched based on the sources and names of +the selected metrics in the scene. For example, if the selected metrics are +from three different hosts, then three copies of a tool may be launched, +one for each host. The behavior of a launch depends on the selected metrics +and the tools being launched. + +On selection of a +.B Launch +menu item +.BR pmview +generates state information in the +.BR pmlaunch (5) +metrics specification format. This provides a description of the selected +metrics (or if there are no selections, all the metrics) in the scene without +any geometry information. + +Tools which can monitor multiple hosts and user specified metrics may be +launched only once for those metrics (eg +.BR pmdumptext (1)). +Other tools which have a fixed view for one host (eg +.BR mpvis (1)), +may be +launched multiple times, once for each host in the selected metric list. If +the launched tools have time controls, they will share the +time controls with the launching +.BR pmview . + +The set of launched tools is configurable, and may include IRIX and user +applications. See +.BR pmlaunch (5) +for more details. +.TP 4n +.B "Help/..." +If +.I pcp.books.help +has been installed, then the +.BR insight (1) +books for +.B pmview +are displayed. +.SH TIME CONTROLS +In addition to the menu options for time controls, the current direction of the +time controls (see +.BR pmtime (1)) +is shown in a button in the top-left corner of the +.B pmview +window. Pressing this button will display the time control and is identical +in behavior to +.BR "Options/Show Time Control" . +.SH SCALE CONTROLS +Above the examiner window is a thumb wheel and an editable text box which +allow the user to apply a multiplier to all values represented in the scene. +Spinning the wheel to the right and/or increasing the text value for the scale +will increase the height of the bars. Spinning the wheel to the left and/or +lowering the text value will decrease the height of the bars. The button to +the right of the thumb wheel will reset the scale so that the bars appear at +the original height for their current value. +.SH TIME INFORMATION +Beside the scale controls is another text box which displays the time of the +fetched metrics. The time will change with the time controller (see +.BR pmtime (1)). +.SH ENVIRONMENT +The default face of the 3D font in the +.B pmview +window can be altered via +.I PMVIEW_FONT +environment variable which can be set to the base name of a Type1 font +file in the default Inventor fonts directory. +.SH FILES +.TP 10 +.B "$PCP_VAR_DIR/pmns/*" +default PMNS specification files +.TP +.B "$PCP_VAR_DIR/config/pmlaunch/pmlaunchrc" +menu specification file - provides a mapping between menu item and +launched program +.TP +.B "$HOME/.pcp/pmlaunch/pmlaunchrc" +individual users menu specification +.TP +.B "/usr/lib/X11/app-defaults/PmView" +application resources +.TP +.B "/usr/lib/images/PmView.icon" +icon for +.BR pmview +.TP +.B "$PCP_SHARE_DIR/lib/pmview-args" +shell procedures for parsing +.B pmview +command line options in front end scripts +.TP +.B "/usr/lib/DPS/outline/base/" +directory where Inventor normally looks for the outlines of Type1 fonts. +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.I /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (4). +.SH SEE ALSO +.BR dkvis (1), +.BR insight (1), +.BR inventor (1), +.BR ivview (1), +.BR mpvis (1), +.BR nfsvis (1), +.BR osvis (1), +.BR oview (1), +.BR pcp (1), +.BR PCPIntro (1), +.BR pmafm (1), +.BR pmcd (1), +.BR pmchart (1), +.BR pmdumptext (1), +.BR pmlogger (1), +.BR pmtime (1), +.BR pmview (1), +.BR X (1), +.BR xconfirm (1), +.BR xlv_vis (1), +.BR pcp.conf (4), +.BR pmview (4), +.BR environ (5) +and +.BR pmlaunch (5). +.P +Relevant information is also available from the on-line PCP +Tutorial. Provided the +.B pcp.man.tutorial +subsystem from the PCP images has been installed, access the +URL +.B file:$PCP_DOC_DIR/Tutorial/pmview.html +from your web browser. + +.SH DIAGNOSTICS +Are intended to be self-explanatory. The environment variable +.B PCP_STDERR +can be set to force most startup warnings and errors to be sent to the +standard error stream rather than posted in a dialog. diff --git a/man/man1/pmwebd.1 b/man/man1/pmwebd.1 new file mode 100644 index 0000000..1f3abcc --- /dev/null +++ b/man/man1/pmwebd.1 @@ -0,0 +1,285 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2013 Red Hat, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMWEBD 1 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmwebd\f1 \- bridge client PMAPI to HTTP +.SH SYNOPSIS +\f3pmwebd\f1 +[\f3\-p\f1 \f2port\f1] +[\f3\-4\f1] +[\f3\-6\f1] +[\f3\-t\f1 \f2timeout\f1] +[\f3\-R\f1 \f2resdir\f1] +[\f3\-c\f1 \f2number\f1] +[\f3\-h\f1 \f2hostname\f1] +[\f3\-a\f1 \f2archive\f1] +[\f3\-L\f1] +[\f3\-N\f1] +[\f3\-K\f1 \f2spec\f1] +[\f3\-A\f1 \f2archdir\f1] +[\f3\-f\f1] +[\f3\-l\f1 \f2logfile\f1] +[\f3\-U\f1 \f2username\f1] +[\f3\-x\f1 \f2file\f1] +[\f3\-v\f1] +[\f3\-?\f1] +.\" see also ../../src/pmwebapi/main.c options[] et al. + +.SH DESCRIPTION +.B pmwebd +is a long-running network daemon. It binds a subset of the +Performance Co-Pilot (PCP) client API (PMAPI) to RESTful web +applications using the HTTP (PMWEBAPI) protocol. Web +clients request a URI with the prefix +.B /pmapi +to access the bindings. pmwebd creates dynamic PCP contexts as requested +by a dynamic pool of remote clients, and maintains them as long as the +clients regularly reconnect to request PMAPI operations. Otherwise, +PCP contexts are closed after a timeout. Permanent contexts may be +requested on the command line. +.PP +In addition to the API binding, pmwebd may be optionally configured as a +simple HTTP file server, in order to feed the web application itself +to a web browser. URIs not matching the +.B /pmapi +prefix are mapped to files under the configured resource directory, if +the \f3\-R\f1 option was given. +.PP +The options to +.B pmwebd +are as follows. +.TP +\f3\-p\f1 \f2port\f1 +Set the TCP port number on which pmwebd will listen for HTTP requests. +The default is 44323. +.TP +\f3\-4\f1 or \f3\-6\f1 +Listen only on IPv4 or IPv6. By default, pmwebd will listen on both +protocols, if possible. +.TP +\f3\-R\f1 \f2resdir\f1 +Activate file serving beneath the given resource directory. All regular +files there may be read & transcribed to remote clients. By default, +file serving is disabled. +.TP +\f3\-t\f1 \f2timeout\f1 +Set the maximum timeout (in seconds) after the last operation on a web +context, before it is closed by pwmebd. A smaller timeout may be requested +by the web client. +.TP +\f3\-c\f1 \f2number\f1 +Reset the next PMWEBAPI permanent context identifier as given. +The default is 1. +.TP +\f3\-h\f1 \f2hostname\f1 or \f3\-a\f1 \f2archive\f1 or \f3\-L\f1 +Assign the next permanent PMWEBAPI context identifier to a PMAPI connection +to the given host (with an extended syntax as given in +.BR PCPIntro (1)), +or archive file, or the PM_CONTEXT_LOCAL. +.TP +\f3\-A\f1 \f2archdir\f1 +Limit remote new-context requests for archives to beneath the given +directory. By default, only files beneath the initial working directory +may be accessed. +.TP +\f3\-N\f1 +Disable creation of new PMWEBAPI contexts via HTTP requests, leaving only +permanent ones accessible. +.TP +\f3\-K\f1 \f2spec\f1 +When +fetching metrics from a local context, the +.B \-K +option may be used to control the DSO PMDAs that should be +made accessible. The +.I spec +argument conforms to the syntax described in +.BR __pmSpecLocalPMDA (3). +More than one +.B \-K +option may be used. +.TP +\f3\-f\f1 +By default +.B pmwebd +is started as a daemon. +The +.B \-f +option indicates that it should run in the foreground. +This is most useful when trying to diagnose problems with establishing +connections. +.TP +\f3\-l\f1 \f2logfile\f1 +By default a log file named +.I pmwebd.log +is written in the current directory. +The +.B \-l +option causes the log file to be written to +.I logfile +instead of the default. +If the log file cannot be created or is not writable, output is +written to the standard error instead. +.TP +\f3\-U\f1 \f2username\f1 +Assume the identity of +.I username +before starting to accept incoming requests from web clients. +.TP +\f3\-x\f1 \f2file\f1 +Before the +.B pmwebd +.I logfile +can be opened, +.B pmwebd +may encounter a fatal error which prevents it from starting. By default, the +output describing this error is sent to +.B /dev/tty +but it may redirected to +.IR file . +.TP +\f3\-v\f1 +Increase the verbosity of the +.B pmwebd +program as it logs to its standard error. +.TP +\f3\-?\f1 +Show pmwebd invocation help and exit. + +.SH SECURITY +.PP +The current release of pmwebd is suitable for direct exposure to +trusted networks only, due to several security limitations. Most or +all of these limitations may be worked around by use of a web +application firewall (for example, an Apache HTTPD proxy), which would +add the constraints and capabilities absent within pmwebd. Such +configuration is beyond the scope of this document. +.TP +encryption/confidentiality +The pmwebd program is does not currently support HTTPS (SSL/TLS), so +the HTTP traffic is not protected against network-level attacks. +.TP +authentication +The PMAPI layer does not possess a mandatory authentication mechanism, +so any remote connection can access any metric exposed by suchly connected +PMAPI contexts. However, a new host-context string may use +authentication clauses of the longer host URLs, for example +.IR pcps://hostname?method=plain&user=userid&pass=password . +.TP +inbound admission control +The pmwebd program does not impose ACLs on the origin or rate of its +incoming requests. It may be possible for some clients to starve others. +.TP +outbound admission control +The pmwebd program does not impose ACLs on outbound connections +when a new PMAPI context is created for a remote third-party PMCD. +For an archive type context, the files must be located under the +pmwebd current directory, or another directory specified by +.BR \-A . +One may entirely disable remotely specified PMAPI context creation using the +.B \-N +option; in this case, specify a static set of contexts using the +.B \-h ", " \-a ", and/or " \-L " options." +You may assign them arbitrary context numbers with the +.B \-c +option. +.TP +context ownership +Authenticated PCP contexts are protected by requiring the same HTTP +PLAIN/simple userid/password credentials for related /pmapi requests. +However, unauthenticated contexts for different web clients are kept +distinct only by the assignment of large pseudorandom identifiers. It +may be possible to find these by brute-force search or other +techniques, thereby letting a web client impersonate another. For +more privacy of the permanent contexts, use the +.B \-c +option to reset their starting web context identifiers to a number +much different from 1. On the other hand, context ownership is not +that precious, since there exist no state-destructive operations for +them, except perhaps instance profile settings. + +.SH "STARTING AND STOPPING PMWEBD" +Normally, +.B pmwebd +is started automatically at boot time and stopped when the +system is being brought down. +Under certain circumstances it is necessary to start or stop +.B pmwebd +manually. +To do this one must become superuser and type +.PP +.ft CS +# $PCP_RC_DIR/pmwebd start +.ft +.PP +to start +.BR pmwebd , +or +.PP +.ft CS +# $PCP_RC_DIR/pmwebd stop +.ft +.PP +to stop +.BR pmwebd . +Starting +.B pmwebd +when it is already running is the same as stopping +it and then starting it again. + +.SH FILES +.PD 0 +.TP +.B PCP_PMWEBDOPTIONS_PATH +command line options +and environment variable settings for +.B pmwebd +when launched from +.B $PCP_RC_DIR/pmwebd +All the command line option lines should start with a hyphen as +the first character. +This file can also contain environment variable settings of +the form "VARIABLE=value". +.TP +.B \&./pmwebd.log +(or +.B $PCP_LOG_DIR/pmwebd/pmwebd.log +when started automatically) +.br +All messages and diagnostics are directed here + +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.I /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). +.SH SEE ALSO +.BR PCPIntro (1), +.BR PMAPI (3), +.BR PMWEBAPI (3), +.BR pcp.conf (5), +.BR pcp.env (5) +and +.BR pmns (5). diff --git a/man/man1/pmwtf.1 b/man/man1/pmwtf.1 new file mode 100644 index 0000000..b0b3bfa --- /dev/null +++ b/man/man1/pmwtf.1 @@ -0,0 +1,167 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2013-2014 Red Hat. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMWTF 1 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmwtf\f1 \- compares archives and report significant differences +.SH SYNOPSIS +\f3pmwtf\f1 +[\f3\-d\f1/\f3--keep\f1] +[\f3\-z\f1/\f3--hostzone\f1] +[\f3\-p\f1/\f3--precision\f1 \f2precision\f1] +[\f3\-q\f1/\f3--threshold\f1 \f2thres\f1] +[\f3\-S\f1/\f3--start\f1 \f2starttime\f1] +[\f3\-T\f1/\f3--finish\f1 \f2endtime\f1] +[\f3\-B\f1/\f3--begin\f1 \f2starttime\f1] +[\f3\-E\f1/\f3--end\f1 \f2endtime\f1] +[\f3\-x\f1 \f2metric\f1] +[\f3\-X\f1 \f2file\f1] +[\f3--skip-excluded\f1] +[\f3--skip-missing\f1] +[\f3\-Z\f1/\f3--timezone\f1 \f2timezone\f1] +\f2archive1\f1 +[\f2archive2\f1] +.SH DESCRIPTION +.B pmwtf +compares the average values for every metric in either one +or two archives, in a given time window, for changes that are +likely to be of interest when searching for performance regressions. +.PP +The archive log has the base name +.I archive +and must have been previously created using +.BR pmlogger (1). +The +.BR pmlogsummary (1) +utility is used to obtain the average values used for comparison. +.PP +There are two sorts of invocation of the tool: with either one or +two archives. +.PP +In the first case, the only sensible command line requires use of +all four time window arguments. These are specified using the same +time window format described in +.BR PCPIntro (1), +and are +.BR \-S / \-\-start +and +.BR \-T / \-\-finish +for the start and end times of the first time window of interest +in the archive, and +.BR \-B / \-\-before +and +.BR \-E / \-\-end +for the start and end times of the second time window of interest. +.PP +In the second case, with two archives, the +.BR \-B / \-\-before +and +.BR \-E / \-\-end +options might be unnecessary. This might be the case, for example, +when comparing the same time window of two consecutive days (usually +two separate archives), or a time window on the same day of different +weeks. +.PP +In either case, +.B pmwtf +produces a sorted summary of those metrics in the specified window +whose values have deviated the most from a minimal threshold. +The level of deviation is calculated by dividing the average value +of each metric in both logs, and then calculating whether the ratio +falls outside of a range considered normal. +This ratio can be adjusted using the +.BR \-q / \-\-threshold +option, and by default it is 2 (i.e. report all metrics with average +values that have more than doubled in the two time windows or more +than halved in the two time windows). +.PP +Should any metrics be present in one window but missing from the +other, a diagnostic will be displayed listing each missing metric +and the archive from which it was missing. +.PP +The remaining options control the specific information to be reported. +Metrics with counter semantics are converted to rates before being +evaluated. +.TP 5 +.BR \-p / \-\-precision +Print all floating point numbers with +.I precision +digits after the decimal place. +.TP +.B \-\-skip-excluded +Cull the list of names of metrics being excluded from the output. +.TP +.B \-\-skip-missing +By default, +.B pmwtf +will report the names of any metrics that are in one archive but not +the other. +This option suppresses that reporting. +.TP +.B \-x +Compare each metric in each archive in the time windows specified +to a given +.BR egrep (1) +pattern, excluding those that match from the report output. +.TP +.B \-X +Allows a +.IR file +to be specified which containing +.BR egrep (1) +patterns which are applied to the metric names to optionally exclude +some from the report. +.TP +.B \-z +Use the local timezone from the given archives. +.TP +.BR \-Z / \-\-timezone +Changes the timezone in the archive labels to +.I timezone +in the format of the environment variable +.B TZ +as described in +.BR environ (5). +.PP +.SH FILES +.PD 0 +.TP 10 +.BI $PCP_LOG_DIR/pmlogger/ hostname +Default directory for PCP archives containing performance +metric values collected from the host +.IR hostname . +.PD +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.I /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). +.SH SEE ALSO +.BR PCPIntro (1), +.BR pmlogger (1), +.BR pmlogsummary (1), +.BR egrep (1), +.BR pcp.conf (5) +and +.BR pcp.env (5). diff --git a/man/man1/telnet-probe.1 b/man/man1/telnet-probe.1 new file mode 100644 index 0000000..5df412d --- /dev/null +++ b/man/man1/telnet-probe.1 @@ -0,0 +1,98 @@ +'\"macro stdmacro +.TH TELNET-PROBE 1 "PCP" "Performance Co-Pilot" +.SH NAME +\f3telnet-probe\f1 \- lightweight telnet-like port probe +.SH SYNOPSIS +\f3$PCP_BINADM_DIR/telnet-probe\f1 +[\f3\-c\f1] +[\f3\-v\f1] +\f2host\f1 \f2port\f1 +.SH DESCRIPTION +.B telnet-probe +allows the +.BR pmdashping (1) +daemons to establish connections to arbitrary local and remote +service-providing daemons so that response time and service +availability information can be obtained. +.PP +The required +.I host +and +.I port +number arguments have the same meaning as their +.BR telnet (1) +equivalents. +.PP +The +.B \-c +option causes +.B telnet-probe +to perform a +.BR connect (2) +only. +This skips the +.BR read (2) +and +.BR write (2) +exercise that would otherwise be done after connecting (see below). +.PP +The +.B \-v +option causes +.B telnet-probe +to be verbose while operating. +.PP +Once the telnet connection has been established, +.B telnet-probe +reads from +.I stdin +until end-of-file, and writes all the input data to the +telnet connection. +Next, +.B telnet-probe +will read from the telnet connection until end-of-file, +discarding whatever data it receives. +Then +.B telnet-probe +exits. +.PP +To operate successfully, the input passed via +.B telnet-probe +to the remote service must be sufficient to cause the remote service to +close the connection when the last line of input has been processed, +e.g. ending with ``quit'' when probing SMTP on port 25. +.PP +By default +.B telnet-probe +will not produce any output, unless there is an error in which case +a diagnostic message can be displayed (in verbose mode only) and the +exit status will be non-zero indicating a failure. +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.I /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). +.SH DIAGNOSTICS +If +.B telnet-probe +succeeds, then 0 will be returned. +If the attempt to establish a connection fails or is terminated, then +a non-zero exit status is returned. +.SH SEE ALSO +.BR PCPintro (1), +.BR pmdashping (1), +.BR pmie (1), +.BR telnet (1), +.BR connect (2), +.BR read (2) +and +.BR write (2). diff --git a/man/man3/GNUmakefile b/man/man3/GNUmakefile new file mode 100644 index 0000000..f2ef6e4 --- /dev/null +++ b/man/man3/GNUmakefile @@ -0,0 +1,36 @@ +# +# Copyright (c) 2013-2014 Red Hat. +# Copyright (c) 2000,2004 Silicon Graphics, Inc. All Rights Reserved. +# +# This program is free software; you can redistribute it and/or modify it +# under the terms of the GNU General Public License as published by the +# Free Software Foundation; either version 2 of the License, or (at your +# option) any later version. +# +# This program is distributed in the hope that it will be useful, but +# WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +# or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +# for more details. +# + +TOPDIR = ../.. +include $(TOPDIR)/src/include/builddefs +-include ./GNUlocaldefs + +MAN_SECTION = 3 +MAN_PAGES = $(shell echo *.3) +MAN_DEST = $(PCP_MAN_DIR)/man$(MAN_SECTION) +LSRCFILES = $(MAN_PAGES) + +default :: $(MAN_PAGES) + +default_pcp : $(MAN_PAGES) + +include $(BUILDRULES) + +install :: install_pcp + +install_pcp : default + $(INSTALL_MAN) + + diff --git a/man/man3/QMC.3 b/man/man3/QMC.3 new file mode 100644 index 0000000..5add074 --- /dev/null +++ b/man/man3/QMC.3 @@ -0,0 +1,50 @@ +'\"macro stdmacro +.\" Copyright (c) 2005 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.TH QMC 3 "SGI" "Performance Co-Pilot" +.SH NAME +\f3QMC\f1 \- library for managing groups of Performance Co-Pilot metrics +.SH "C++ SYNOPSIS" +.ft 3 +#include <QMC.h> +.sp +CC ... \-lqmc \-lpcp +.ft 1 +.SH DESCRIPTION +The Qt-based Performance Metrics Class +.RB ( QMC ) +class library is a collection of C++ classes for managing a large set of +performance metrics from a variety of sources. This library is built over +.BR PMAPI (3). +.SH SEE ALSO +.BR PMAPI (3), +.BR QmcContext (3), +.BR QmcDesc (3), +.BR QmcGroup (3), +.BR QmcIndom (3), +.BR QmcMetric (3), +.BR QmcSource (3), +.BR pmflush (3) +and +.BR pmprintf (3). +.SH DIAGNOSTICS +Error messages are generated using +.BR pmprintf (3) +but are not flushed. It is the responsibility of the user to call +.BR pmflush (3) +to output any messages. +.PP +Additional diagnostics may be activated by adding +.B DBG_TRACE_PMC +to the global +.IR pmDebug . diff --git a/man/man3/QmcContext.3 b/man/man3/QmcContext.3 new file mode 100644 index 0000000..9e6be22 --- /dev/null +++ b/man/man3/QmcContext.3 @@ -0,0 +1,132 @@ +'\"macro stdmacro +.\" Copyright (c) 2005 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.TH QMC_CONTEXT 3 "SGI" "Performance Co-Pilot" +.SH NAME +\f3QmcContext\f1 \- container for a PMAPI context and its metrics +.SH "C++ SYNOPSIS" +.ft 3 +#include <QmcContext.h> +.sp +CC ... \-lqmc \-lpcp +.ft 1 +.SH DESCRIPTION +A +.B QmcContext +object is a container for a single +.BR PMAPI (3) +context. The object maintains a list of all the metric descriptors +.RB ( QmcDesc ), +instance domains +.RB ( QmcIndom ) +and +metrics +.RB ( QmcMetric ) +using the context to minimize the duplication of these objects. +.SH "CONSTRUCTORS" +A +.B QmcContext +object should be constructed through the +.B QmcGroup::use +interface. +.SH "DESCRIPTOR LOOKUP" +The metric and instance domain descriptors are cached by the +.B QmcContext +object to reduce duplicate +.BR QmcDesc (3) +and +.BR QmcIndom (3) +objects and +.BR PMAPI (3) +calls required to create them. Also the mapping from metrics names to +.BR pmID s +is also maintained to avoid +.BR pmLookupName (3) +calls. +.TP 4 +.B "int lookupDesc(const char *name, pmID& id);" +Search for the metric +.I name +in the name list and set +.B id +to the known +.BR pmID . +If not found, use +.BR pmLookupName (3) +to get the mapping. If this call fails, the +.BR PMAPI (3) +error code will be returned. +.TP +.B "int lookupDesc(const char *name, uint_t& desc, uint_t& indom);" +Find the index +.I desc +and +.I indom +to the +.B QmcDesc +object and the +.B QmcIndom +object for the metric +.IR name . +The indexes can then be used with +.B QmcContext::desc +and +.B QmcContext::indom +to obtain references to the real objects. +The methods will return a +.BR PMAPI (3) +error code if the metric descriptor or instance domain could not be obtained. +.TP +.B "int lookupDesc(pmID pmid, uint_t& desc, uint_t& indom);" +Find the index +.I desc +and +.I indom +to the +.B QmcDesc +object and the +.B QmcIndom +object for the metric +.IR pmid . +The indexes can then be used with +.B QmcContext::desc +and +.B QmcContext::indom +to obtain references to the real objects. +The methods will return a +.BR PMAPI (3) +error code if the metric descriptor or instance domain could not be obtained. +.SH SEE ALSO +.BR PMAPI (3), +.BR QMC (3), +.BR QmcDesc (3), +.BR QmcGroup (3), +.BR QmcIndom (3), +.BR QmcMetric (3), +.BR pmflush (3), +.BR pmLookupName (3) +and +.BR pmprintf (3). +.SH DIAGNOSTICS +Error messages are generated using +.BR pmprintf (3) +but are not flushed. It is the responsibility of the user to call +.BR pmflush (3) +to output any messages. +.PP +Additional diagnostics may be activated by adding +.B DBG_TRACE_PMC +and +.B DBG_TRACE_OPTFETCH +to the global +.IR pmDebug . diff --git a/man/man3/QmcDesc.3 b/man/man3/QmcDesc.3 new file mode 100644 index 0000000..0269554 --- /dev/null +++ b/man/man3/QmcDesc.3 @@ -0,0 +1,96 @@ +'\"macro stdmacro +.\" Copyright (c) 2005 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.TH QMC_DESC 3 "SGI" "Performance Co-Pilot" +.SH NAME +\f3QmcDesc\f1 \- container for a metric description +.SH "C++ SYNOPSIS" +.ft 3 +#include <QmcDesc.h> +.sp +CC ... \-lqmc \-lpcp +.ft 1 +.SH DESCRIPTION +A +.B QmcDesc +object is a container for a metric descriptor +.RB ( pmDesc ", see " PMAPI (3)) +and units. +.SH "CONSTRUCTORS & DESTRUCTOR" +.TP 4 +.B "~QmcDesc();" +Destructor. +.TP +.B "QmcDesc(pmID pmid);" +Construct a container for the descriptor for +.IR pmid . +The descriptor is obtained from the current +.BR PMAPI (3) +context using +.BR pmLookupDesc (3). +.SH DESCRIPTION +.TP 4 +.B "int status() const;" +A status less than zero indicates that the descriptor could not be obtained, +the +.BR PMAPI (3) +error is encoded in the result. +.TP +.B "pmID id() const;" +Return the +.B pmID +for this descriptor. +.TP +.B "pmDesc desc() const;" +Return a copy of the actual metric descriptor. +.TP +.B "const pmDesc *descPtr() const;" +Return a pointer to the actual descriptor to avoid using a pointer to a +temporary. +.SH UNITS +.TP 4 +.B "const QString &units() const;" +The complete unit string for this descriptor. +.TP +.B "const QString &abvUnits() const;" +The unit string using abbreviations. +.TP +.B "bool useScaleUnits() const;" +Returns +.B true +if the units have been set by a call to +.BR QmcDesc::setScaleUnits . +.TP +.B "const pmUnits &scaleUnits() const;" +Return the scaling units for this descriptor. +.TP +.B "void setScaleUnits(const pmUnits &units);" +Set the scaling units for this descriptor. +.SH SEE ALSO +.BR PMAPI (3), +.BR QMC (3), +.BR pmflush (3), +.BR pmLookupDesc (3) +and +.BR pmprintf (3). +.SH DIAGNOSTICS +Error messages are generated using +.BR pmprintf (3) +but are not flushed. It is the responsibility of the user to call +.BR pmflush (3) +to output any messages. +.PP +Additional diagnostics may be activated by adding +.B DBG_TRACE_PMC +to the global +.IR pmDebug . diff --git a/man/man3/QmcGroup.3 b/man/man3/QmcGroup.3 new file mode 100644 index 0000000..0784aee --- /dev/null +++ b/man/man3/QmcGroup.3 @@ -0,0 +1,257 @@ +'\"macro stdmacro +.\" Copyright (c) 2005 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.TH QMC_GROUP 3 "SGI" "Performance Co-Pilot" +.SH NAME +\f3QmcGroup\f1 \- container representing a single fetch group of metrics from +multiple sources +.SH "C++ SYNOPSIS" +.ft 3 +#include <QmcGroup.h> +.sp +CC ... \-lqmc \-lpcp +.ft 1 +.SH DESCRIPTION +A +.B QmcGroup +object is a container for contexts and metrics that should be fetched at +the same time. The class manages the +.BR QmcContext (3) +objects, timezones and bounds for every context created with +.B QmcGroup::use +and +.BR QmcGroup::addMetric . +.SH "CONSTRUCTORS & DESTRUCTOR" +.TP 4 +.B "~QmcGroup();" +Destructor which destroys all metrics and contexts created by this group. +.TP +.B "QmcGroup(bool restrictArchives = false);" +Construct a new fetch group. +.I restrictArchives +will restrict the creating of multiple archive contexts created from the same +host. +.SH "CONTEXTS" +The default context of the group is defined as the first context created with +.B QmcGroup::use +before the first call to +.BR QmcGroup::addMetric . +If no context is created before the first metric is added, the localhost +is used as the default context. Therefore, if any metrics specifications +contain archive sources, an archive source must have been created with +.B QmcGroup::use +to avoid an error for mixing context types. +.TP 4 +.B "uint_t numContexts() const;" +The number of valid contexts created in this group. +.TP +.B "QmcContext const& context(uint_t index) const" +Return a handle to a context. +.TP +.B "QmcContext& context(uint_t index);" +Return a modifiable handle to a context. +.TP +.B "int mode() const;" +Return the type of context, either +.BR PM_CONTEXT_LOCAL , +.B PM_CONTEXT_HOST +or +.BR PM_CONTEXT_ARCHIVE . +.TP +.B "QmcContext* which() const;" +Return a handle to the current context of this group. This does not +call +.BR pmUseContext (3) +so it may not be the current +.BR PMAPI (3) +context. +.TP +.B "uint_t whichIndex() const" +The index to the current group context. +.TP +.B "int use(int type, char const* source);" +Use the context of +.I type +from +.IR source . +If a context to this +.I source +already exists in this group, that context will become the current +.BR PMAPI (3) +context. Otherwise a new context will be created. The result is the +.BR PMAPI (3) +context handle +for the +.B QmcGroup::context +or a +.BR PMAPI (3) +error code if the context failed. +.TP +.B "bool defaultDefined() const;" +Returns +.B true +if a default context has been determined. +.TP +.B "int useDefault();" +Use the default context. If a default context has not been created, the +context to the local host will be attempted. A result less than zero indicates +that the method failed with the +.BR PMAPI (3) +error encoded in the result. +.TP +.B "void createLocalContext();" +Create and use a context to the local host. A result less than zero indicates +that the method failed with the +.BR PMAPI (3) +error encoded in the result. +.SH "METRICS" +These +.B addMetric +methods should be used to create new metrics as the +.B QmcMetric +constructors are private. These methods will always return a pointer to +a +.B QmcMetric +object, however the +.B QmcMetric::status() +field should be checked to ensure the metric is valid. +.TP 4 +.B "QmcMetric* addMetric(char const* str, double theScale = 0.0," +.B "bool active = false);" + +Add the metric +.I str +to the group, with a scaling factor of +.IR scale . +If +.I active +is set the metric will use only active instances (see +.BR QmcMetric (3)). +.TP +.B "QmcMetric* addMetric(pmMetricSpec* theMetric, double theScale" +.B "= 0.0, bool active);" + +Add the metric +.I theMetric +to the group, with a scaling factor of +.IR scale . +If +.I active +is set the metric will use only active instances (see +.BR QmcMetric (3)). +.TP +.B "int fetch(bool update = true);" +Fetch all the metrics in all the contexts in this group. If +.I update +is equal to +.BR true , +all counter metrics will be automatically converted to rates (see +.BR QmcMetric (3)). +.TP +.B "int setArchiveMode(int mode, const struct timeval *when," +.B "int interval);" + +Set the mode and time to access all archive contexts in this group. See +.BR pmSetmode (3) +for more details. +.SH TIMEZONES +These methods assist in the management of multiple timezones and help to +control the current timezone. +.TP 4 +.B "enum TimeZoneFlag { localTZ, userTZ, groupTZ, unknownTZ };" +Enumeration used to describe the origin of the default timezone. +.BR localTZ , +.B userTZ +and +.B groupTZ +indicate that the timezone was set with +.BR "QmcGroup::useLocalTZ" , +.BR "QmcGroup::useTZ(QString const&)" +and +.BR "QmcGroup::useTZ()" +respectively. +.B unknownTZ +indicates that a timezone has not been set. +.B userTZ +indicates that the timezone was +.TP +.B "int useTZ();" +Use the timezone of the current group context as the default. +.TP +.B "int useTZ(const QString &tz);" +Add and use +.I tz +as the default timezone of this group. +.TP +.B "int useLocalTZ();" +Use the timezone of the localhost as the default for this group. +.TP +.B "void defaultTZ(QString &label, QString &tz);" +Return the +.I label +and +.I tz +string of the default timezone of this group. +.TP +.B "TimeZoneFlag defaultTZ() const" +Return the origin of the default timezone. +.TP +.B "int useDefaultTZ();" +Set the timezone to be the default timezone as defined in a previous call +to +.B QmcGroup::useTZ +or +.BR QmcGroup::useLocalTZ . +.TP +.B "struct timeval const& logStart() const;" +Return the earliest starting time of any archives in this group. Assumes that +.B QmcGroup::updateBounds +has been called. +.TP +.B "struct timeval const& logEnd() const;" +Return the latest finish time of any archives in this group. Assumes that +.B QmcGroup::updateBounds +has been called. +.TP +.B "void updateBounds();" +Determine the earliest start and latest finish times of all archives in this +group. +.TP +.B "int sendTimezones();" +Send the current timezones to +.B kmtime (3). +.SH "DEBUGGING" +.TP 4 +.B "void dump(ostream &os);" +Dump state information about this group to +.IR os . +.SH SEE ALSO +.BR PMAPI (3), +.BR QMC (3), +.BR QmcContext (3), +.BR QmcMetric (3), +.BR pmflush (3), +.BR pmprintf (3) +and +.BR pmSetMode (3). +.SH DIAGNOSTICS +Error messages are generated using +.BR pmprintf (3) +but are not flushed. It is the responsibility of the user to call +.BR pmflush (3) +to output any messages. +.PP +Additional diagnostics may be activated by adding +.B DBG_TRACE_PMC +to the global +.IR pmDebug . diff --git a/man/man3/QmcIndom.3 b/man/man3/QmcIndom.3 new file mode 100644 index 0000000..4c54a0e --- /dev/null +++ b/man/man3/QmcIndom.3 @@ -0,0 +1,200 @@ +'\"macro stdmacro +.\" Copyright (c) 2005 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.TH QMC_INDOM 3 "SGI" "Performance Co-Pilot" +.SH NAME +\f3QmcIndom\f1 \- container for a instance domain description +.SH "C++ SYNOPSIS" +.ft 3 +#include <QmcIndom.h> +.sp +CC ... \-lqmc \-lpcp +.ft 1 +.SH DESCRIPTION +A +.B QmcIndom +object represents a +.BR PMAPI (3) +instance domain. This includes a description of all the instances +in the instance domain. +.PP +A +.B QmcInstance +is a structure used to describe each instance in the instance domain. This +includes: +.PP +.in 1.0i +- internal identifier. If this is less than zero, the instance is treated as a +NULL entry in the instance table. + +- external name + +- reference count, ie. the number of +.B QmcMetric +objects referring to this instance. + +- the likely position of the instance in the +.B pmResult +from a +.BR pmFetch (3). +This is also used to indicate the position of the next NULL instance +in the instance table, if this entry is also NULL. + +- a flag indicating if the instance was in the last +.BR pmGetInDom (3). +.in +.PP +The +.B QmcIndom +object has a list of +.B QmcInstance +structures, and various flags and counters to support dynamic instance domains +where instances may come and go with each fetch and efficient profile +generation. +.in +.SH CONSTRUCTORS +.TP 4 +.B "QmcIndom::QmcIndom(int type, QmcDesc &desc);" +Calls +.BR pmGetInDom (3) +and +.BR pmGetInDomArchive (3) +for host and archive contexts to obtain the entire instance list for the +instance domain of +.I type +and identified in +.IR desc . +.SH "DYNAMIC INDOMS" +The support of dynamic instance domains for live contexts is complex since many +metrics may be referencing any of the instances in the domain. Therefore the +instance list may be sparse as the position of instances in the list must be maintained. +.PP +When the instance domain is updated, instances may be removed from the list if +they are not in the new instance list (as returned by +.BR pmGetInDom (3)) +and is not referenced by any metrics. Each instance in the new list is then +compared with the old list to determine which instances are still active, and +any new instances need to be added. An instance is considered the same if both +the internal and external identifiers are the same. New instances are first +inserted into positions of deleted instances before being appended to the list. +.PP +This algorithm is expensive (potentially O(N^2)). +.TP 4 +.B "bool changed() const;" +Returns +.B true +if the instance domain may have changed in the last fetch. +.TP +.B "void newFetch();" +Reset the flags that may have indicated that the instance domain had changed. +This is called by +.BR QmcContext::fetch . +.TP +.B "void hasChanged();" +Set the flags to indicate that the instance domain may have changed. This is +called by +.BR QmcMetric::extractValues . +.TP +.B "int update();" +Update the instance domain as described above. On subsequent calls, before the +next fetch, this method will remove any instances that are no longer referenced +without updating the instance list with a +.BR pmGetInDom (3) +call. +.TP +.B "uint_t numInsts() const;" +Returns the number of instances that are not NULL. +.TP +.B "uint_t numActiveInsts() const;" +Returns the number of instances that are active according to the last +.B QmcIndom::update +call. +.TP +.B "uint_t listLen() const;" +Returns the length of the instance list, including NULL instances. +.SH "PROFILES" +The algorithm for determining the most compact profile uses the number of +instances +.RB ( _instances.length() ), +the number of referenced instances +.RB ( _count ), +the number of active instances +.RB ( _numActive ) +and the number of referenced active instances +.RB ( _numActiveRef ). +.PP +.in 1.5i +.ft CW +.nf +if (all active instances are referenced + or there are no active instances) + + request all instances implicitly + +else if (the number of referenced instances + is less than the number of active + instances that are not referenced) + + delete all instances from profile + add all referenced instances + +else + + add all instances to profile + delete all instances that are not referenced +.fi +.ft R +.in +.TP 4 +.B "bool diffProfile() const;" +Returns +.B true +if the profile has potentially changed since the last call to +.BR QmcIndom::genProfile . +.TP +.B "int genProfile();" +Generates a new profile for the instance domain. a +.BR PMAPI (3) +error code is returned if the profile failed. +.SH SEE ALSO +.BR PMAPI (3), +.BR QMC (3), +.BR QmcContext (3), +.BR QmcDesc (3), +.BR QmcMetric (3), +.BR pmFetch (3), +.BR pmflush (3), +.BR pmGetInDom (3), +.BR pmGetInDomArchive (3) +and +.BR pmprintf (3). +.SH DIAGNOSTICS +Error messages are generated using +.BR pmprintf (3) +but are not flushed. It is the responsibility of the user to call +.BR pmflush (3) +to output any messages. +.PP +Additional diagnostics may be activated by adding +.B DBG_TRACE_PMC +and +.B DBG_TRACE_INDOM +to the global +.IR pmDebug . +.SH BUGS +User's have no control over the algorithm used to generate the profile. In +the case of +.I proc +metrics, an implicit profile could be generated if all process instances are +required, even though this will result in no values being returned in the +fetch. diff --git a/man/man3/QmcMetric.3 b/man/man3/QmcMetric.3 new file mode 100644 index 0000000..d0d9cb1 --- /dev/null +++ b/man/man3/QmcMetric.3 @@ -0,0 +1,105 @@ +'\"macro stdmacro +.\" Copyright (c) 2005 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.TH QMC_METRIC 3 "SGI" "Performance Co-Pilot" +.SH NAME +\f3QmcMetric\f1 \- container for a metric and all its values +.SH "C++ SYNOPSIS" +.ft 3 +#include <pcp/pmc/Metric.h> +.sp +CC ... \-lpcp_pmc \-lpcp +.ft 1 +.SH DESCRIPTION +A +.B QmcMetric +object is a container for a single metric and all its values. +.PP +The +.B QmcMetricValue +structure is used to hold the instance index, values and errors of each +instance. In the case of a singular metric, a single +.B QmcMetricValue +object is used. +.PP +A +.B QmcMetric +object consists of a list of +.B QmcMetricValue +objects, indexes to the descriptors in the metric's +.B QmcGroup +and +.B QmcContext +and flags to indicate if the instances are explicit or implicit, and if +only active metrics are required after +.B QmcMetric::updateIndom +is called. +.SH "CONSTRUCTORS" +Metrics should be constructed through the +.B QmcGroup::addMetric +methods as this will ensure that the references to the metric's context, +descriptor and instance domain are correctly initialized. +.SH INSTANCES +For metrics with an instance domain it is possible to add and remove any +instance, and also update the instance list to reflect changes in a dynamic +instance domain. +.TP 4 +.B "bool updateIndom();" +Update the metric to include new instances. This method will first call +.B QmcContext::update +to update the instance domain. If the +.I active +flag is set in the +.B QmcGroup::addMetric +call, only instances will exported by the metric, otherwise the metric will +export all instances listed in the domain. + +The ordering of instances may change as a result of this call. Instances +that already existed will keep their current and previous values and errors, +even if they are in a different order. +.TP +.B "int addInst(QString const& name);" +Add the instance +.B name +to the metric. If the instance does not exist in the instance domain, +a +.BR PMAPI (3) +error will be returned. This method ignores the value of the +.I active +flag set in the +.B QmcMetric +constructor. +.TP +.B "void removeInst(uint_t index);" +Remove the instance at position +.I index +from the metric. +.SH SEE ALSO +.BR PMAPI (3), +.BR QMC (3), +.BR QMC_Context (3), +.BR QMC_Group (3), +.BR pmflush (3) +and +.BR pmprintf (3). +.SH DIAGNOSTICS +Error messages are generated using +.BR pmprintf (3) +but are not flushed. It is the responsibility of the user to call +.BR pmflush (3) +to output any messages. +.PP +Additional diagnostics may be activated by adding +.B DBG_TRACE_PMC +to the global +.IR pmDebug . diff --git a/man/man3/QmcSource.3 b/man/man3/QmcSource.3 new file mode 100644 index 0000000..122b3f8 --- /dev/null +++ b/man/man3/QmcSource.3 @@ -0,0 +1,120 @@ +'\"macro stdmacro +.\" Copyright (c) 2005 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.TH QMC_SOURCE 3 "SGI" "Performance Co-Pilot" +.SH NAME +\f3QmcSource \f1 \- manages contexts created by all groups +.SH "C++ SYNOPSIS" +.ft 3 +#include <QmcSource.h> +.sp +CC ... \-lqmc \-lpcp +.ft 1 +.SH DESCRIPTION +The +.B QmcSource +class maintains a unique list of all metric sources in use to minimize +the creation of new contexts (see +.BR pmNewContext (3)) +when the context could have been duplicated (see +.BR pmDupContext (3)). +This also reduces the duplication of descriptions of each source. +.PP +In general, +.B QMC +users should only need to access +.B QmcSource +methods to obtain source descriptions for a +.BR QmcContext (3) +object. All context creation by the user should be handled through +.BR QmcGroup (3). +.SH "DESTRUCTOR" +.TP 4 +.B "~QmcSource();" +Destructor. +.SH "CONSTRUCTORS" +.TP 4 +.B "static QmcSource* getSource(int type, const char* source," +.B "bool matchHosts)" + +This method will return a +.B QmcSource +object that represents a context of +.I type +to +.IR source . +The +.B QmcSource +object may be a new object if the +.I source +has not been previously requested. Memory management of the +.B QmcSource +objects is handled by +.BR QmcSource . +If all +.BR QmcContext (3)s +to the +.B QmcSource +have been deleted, the +.B QmcSource +object will also be deleted. + +The +.I matchHosts +flag controls the algorithm that is used to match hosts to archives. +If +.I matchHosts +is equal to +.B false +then no attempt will be made by this method to match a host context to an +existing source context. A +.B QmcSource +object will always be returned in this case, although the +.B QmcSource::status +method may indicate that a context to +.I source +failed. + +If +.I matchHosts +is equal to +.BR true , +host contexts will be matched to a pre-defined archive source collected from +that +.IR source . +If no archive sources for the +.I source +have been previous specified, +.B getSource +will return a NULL pointer. +.SH SEE ALSO +.BR PMAPI (3), +.BR QMC (3), +.BR QmcContext (3), +.BR QmcGroup (3), +.BR pmDupContext (3), +.BR pmflush (3), +.BR pmNewContext (3) +and +.BR pmprintf (3). +.SH DIAGNOSTICS +Error messages are generated using +.BR pmprintf (3) +but are not flushed. It is the responsibility of the user to call +.BR pmflush (3) +to output any messages. +.PP +Additional diagnostics may be activated by adding +.B DBG_TRACE_PMC +to the global +.IR pmDebug . diff --git a/man/man3/logimport.3 b/man/man3/logimport.3 new file mode 100644 index 0000000..469c67f --- /dev/null +++ b/man/man3/logimport.3 @@ -0,0 +1,110 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2010 Ken McDonell. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH LOGIMPORT 3 "" "Performance Co-Pilot" +.SH NAME +\f3LOGIMPORT\f1 \- introduction to the library for importing data and creating a PCP archive +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.br +#include <pcp/impl.h> +.br +#include <pcp/import.h> +.sp +cc ... \-lpcp_import \-lpcp +.ft 1 +.SH "Perl SYNOPSIS" +.ft 3 +use PCP::LogImport; +.ft 1 +.SH DESCRIPTION +The Performance Co-Pilot Log Import (LOGIMPORT) API is a library (and Perl wrapper) +that supports the creation of PCP archives from external sources of +performance data, either in the form of historical logs and spreadsheets +or from real-time sources that are +.B not +integrated as a Performance Metrics +Domain Agent (PMDA) under the control of +.BR pmcd (1). +.PP +The typical usage for LOGIMPORT would involve: +.IP \(bu 3n +An initial call to +.BR pmiStart (3). +.IP \(bu 3n +Optional calls to +.BR pmiSetHostname (3) +and/or +.BR pmiSetTimezone (3) +to set the hostname and timezone for the source of the performance data. +.IP \(bu 3n +One or more calls to +.BR pmiAddMetric (3) +to define performance metrics. +.IP \(bu 3n +One or more calls to +.BR pmiAddInstance (3) +to define instances associated with the metrics. +.IP \(bu 3n +Optional calls to +.BR pmiGetHandle (3) +to defined convenience handles for metric-instance pairs. +.IP \(bu 3n +A main loop in which performance data is injested and for each +sample time interval, the PCP archive record is constructed by calls +to +.BR pmiPutValue (3) +and/or +.BR pmiPutValueHandle (3), +followed by a call to +.BR pmiWrite (3) +to flush all data and any associated new metadata +to the PCP archive. Alternatively, +.BR pmiPutResult (3) +could be used to package and process all the data for one sample time +interval. +.IP \(bu 3n +Once the input source of data has been consumed, calling +.BR pmiEnd (3) +to complete the PCP archive creation and close all open files. +.PP +If new metrics and/or instances are discovered during the data +injestion, these can be added by subsequent calls to +.BR pmiAddMetric (3) +and/or +.BR pmiAddInstance (3), +provided all the metrics and instances have been defined before +a call to +.BR pmiGetHandle (3), +.BR pmiPutValue (3) or +.BR pmiPutResult (3) +that references those metrics and instances. +.SH SEE ALSO +.BR pmcd (1), +.BR pmlogger (1), +.BR pmiGetHandle (3), +.BR pmiAddInstance (3), +.BR pmiAddMetric (3), +.BR pmiEnd (3), +.BR pmiErrStr (3), +.BR pmiPutResult (3), +.BR pmiPutValue (3), +.BR pmiPutValueHandle (3), +.BR pmiSetHostname (3), +.BR pmiSetTimezone (3), +.BR pmiStart (3) +and +.BR pmiWrite (3). diff --git a/man/man3/mmv_inc_value.3 b/man/man3/mmv_inc_value.3 new file mode 100644 index 0000000..5204aea --- /dev/null +++ b/man/man3/mmv_inc_value.3 @@ -0,0 +1,42 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2009 Max Matveev +.\" Copyright (c) 2009 Aconex. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH MMV_INC_VALUE 3 "" "Performance Co-Pilot" +.SH NAME +\f3mmv_inc_value\f1 - update a value in a Memory Mapped Value file +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.br +#include <pcp/mmv_stats.h> +.sp +void mmv_inc_value(void *\fIaddr\fP, pmAtomValue *\fIval\fP, double \fIinc\fP); +.sp +cc ... \-lpcp_mmv \-lpcp +.ft 1 +.SH DESCRIPTION +.P +\f3mmv_inc_value\f1 provides a convenient way of updating a value +returned by the \f3mmv_lookup_value_desc\f1. +\f2addr\f1 is the address returned from \f3mmv_stats_init\f1(). +.P +The value of the \f2inc\f1 is internally cast to match the type of +the metric and then added to the previous value of the metric. +.SH SEE ALSO +.BR mmv_stats_init (3), +.BR mmv_lookup_value_desc (3) +and +.BR mmv (5). diff --git a/man/man3/mmv_lookup_value_desc.3 b/man/man3/mmv_lookup_value_desc.3 new file mode 100644 index 0000000..ac7a5ad --- /dev/null +++ b/man/man3/mmv_lookup_value_desc.3 @@ -0,0 +1,69 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2009 Max Matveev +.\" Copyright (c) 2009 Aconex. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH MMV_LOOKUP_VALUE_DESC 3 "" "Performance Co-Pilot" +.SH NAME +\f3mmv_lookup_value_desc\f1 - find a value in the Memory Mapped Value file +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.br +#include <pcp/mmv_stats.h> +.sp +.ad l +.hy 0 +.in +8n +.ti -8n +pmAtomValue *mmv_lookup_value_desc(void *\fIaddr\fP, const char *\fImetric\fP, const\ char\ *\fIinst\fP); +.sp +.in +.hy +.ad +cc ... \-lpcp_mmv \-lpcp +.ft 1 +.SH DESCRIPTION +.P +\f3mmv_lookup_value_desc\f1 searches for the value of the instance +identified by the external instance name \f2inst\f1 of the metric +\f2metric\f1 in the \f3MMV\f1(5) file. +\f2addr\f1 is the address returned from \f3mmv_stats_init\f1(). +.P +The pointer returned points to a pmAtomValue union, which is +defined as follows: +.P +.nf + 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 */ + pmValueBlock *vbp; /* pmValueBlock ptr */ + } pmAtomValue; +.fi +.P +MMV string values should be set using either of the +\f3mmv_set_string\f1 or \f3mmv_set_strlen\f1 routines. +.SH RETURNS +The function returns the address inside of the memory mapped region +on success or NULL on failure. +.SH SEE ALSO +.BR mmv_stats_init (3), +.BR mmv_inc_value (3) +and +.BR mmv (5). diff --git a/man/man3/mmv_stats_init.3 b/man/man3/mmv_stats_init.3 new file mode 100644 index 0000000..216ed02 --- /dev/null +++ b/man/man3/mmv_stats_init.3 @@ -0,0 +1,110 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2013 Red Hat. +.\" Copyright (c) 2009 Max Matveev. +.\" Copyright (c) 2009 Aconex. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH MMV_STATS_INIT 3 "" "Performance Co-Pilot" +.SH NAME +\f3mmv_stats_init\f1 - create and initialize Memory Mapped Value file +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.br +#include <pcp/mmv_stats.h> +.sp +.ad l +.hy 0 +.in +8n +.ti -8n +void *mmv_stats_init(const char *\fIname\fP, int \fIcluster\fP, mmv_stats_flags_t\ \fIflags\fP, const\ mmv_metric_t\ *\fIstats\fP, int\ \fInstats\fP, mmv_indom_t\ *\fIindoms\fP, int\ \fInindoms\fP); +.sp +.in +.hy +.ad +cc ... \-lpcp_mmv \-lpcp +.ft 1 +.SH DESCRIPTION +.P +\f3mmv_stats_init\f1 creates and initializes the content of the +\f2MMV\f1(5) file, returning a handle that is used in subsequent +MMV API calls. +.P +\f3mmv_stats_stop\f1 performs an orderly shutdown of the mapping +handle returned by an earlier initialization call. +.P +The file is created in the $PCP_TMP_DIR/mmv directory, \f2name\f1 +argument is expected to be a basename of the file, not the full path. +The metadata content of the file does not change after the file has +been created. +.P +The old file is removed unconditionally unless there was an error. +.P +\f2cluster\f1 is the preferred MMV PMDA cluster ID to be used for +the metrics originating from this call to \f3mmv_stats_init\f1. +The \f2flags\f1 provide additional control over the behaviour +of the MMV PMDA - e.g. use of MMV_FLAG_PROCESS will ensure values +are only exported when the instrumented application is running \- +this is verified on each request for new values. +.P +\f2stats\f1 is the array of \f3mmv_metric_t\f1 elements of length +\f2nstats\f1. Each element of the array describes one PCP metric. +.P +.nf + typedef struct { + char name[MMV_NAMEMAX]; /* Name of the metric */ + __uint32_t item; /* Item component of PMID */ + mmv_metric_type_t type; /* Type of the metric */ + mmv_metric_sem_t semantics; /* Semantics of the metric */ + pmUnits dimension; /* Dimensions (TIME,SPACE,etc) */ + __uint32_t indom; /* Instance domain identifier */ + char *shorttext; /* Optional, one-line help */ + char *helptext; /* Optional, full help text */ + } mmv_metric_t; +.fi +.P +If \f3indom\f1 is not zero and not PM_INDOM_NULL, then the metric has +multiple values and there must be a corresponding \f2indom\f1 entry +in the \f2indom\f1 list (uniquely identified by \f3serial\f1 number). +.P +The \f2stats\f1 array cannot contain any elements which have no name - +this is considered an error and no metrics will be exported in this case. +.P +\f2indoms\f1 is the array of \f3mmv_indom_t\f1 elements of length +\f2nindoms\f1. Each element of the array describes one PCP instance +domain. +.P +.nf + typedef struct { + __int32_t internal; + char external[MMV_NAMEMAX]; + } mmv_instances_t; + + typedef struct { + __uint32_t serial; /* Unique serial number */ + __uint32_t count; /* Number of instances */ + mmv_instances_t *instances; /* Internal/external IDs */ + char *shorttext; /* Short help text */ + char *helptext; /* Long help text */ + } mmv_indom_t; +.fi +.P +.SH RETURNS +The function returns the address of the memory mapped region on success or +NULL on failure. +.SH SEE ALSO +.BR mmv_inc_value (3), +.BR mmv_lookup_value_desc (3) +and +.BR mmv (5). diff --git a/man/man3/pcpintro.3 b/man/man3/pcpintro.3 new file mode 100644 index 0000000..9bfb07c --- /dev/null +++ b/man/man3/pcpintro.3 @@ -0,0 +1,637 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PCPINTRO 3 "PCP" "Performance Co-Pilot" +.SH NAME +\f3PCPIntro\f1 \- introduction to the Performance Co-Pilot (PCP) libraries +.SH INTRODUCTION +Performance Co-Pilot (PCP) is a toolkit designed for monitoring +and managing system-level performance. +.PP +The PCP libraries support the APIs required to create new performance +monitoring tools and new agents (or PMDAs) to export performance data. +The +.B libpcp +library is used in both cases. The +.B libpcp_pmda +library is used only for PMDAs. +.PP +Individual library routines are documented in their own manual page entries. +.PP +Most routines return an integer value; greater than equal to zero for +success and less than zero for an error. The error codes have +symbolic names defined in +.BR <pcp/pmapi.h> . +Other negative values are used to encode errors that can be mapped to +the traditional +.I errno +values defined in +.BR <errno.h> , +with the value negated. +To translate all PCP error codes into useful messages use +either +.BR pmerr (1) +or +.BR pmErrStr (3); +the latter may also be used to decode the +.I \-errno +cases. +.SH "GENERAL ERRORS" +These common errors may occur in various PCP interactions. +.TP 4n +.B PM_ERR_TIMEOUT +.I "Timeout waiting for a response from PMCD" +.br +Many interactions between PCP applications involve +synchronous message passing, and these are subject to +timeout constraints. These errors are most frequently +encountered when using network connections with slow +data rates or long latencies. +.RS +.PP +For client\-\c +.B pmcd +timeouts, refer to +.BR PCPIntro (1) +for environment variables that may be used to modify +the timeout thresholds. +For +.BR pmcd -PMDA +timeouts refer to the +.B \-t +and +.B \-q +options of +.BR pmcd (1) +and the PCP metric +.B pmcd.control.timeout +that can be dynamically changed with +.BR pmstore (1). +.RE +.TP +.B PM_ERR_APPVERSION +.I "Metric not supported by this version of monitored application" +.br +Some performance metrics are unavailable from specific versions +of the associated PMDA, or may be unavailable because the underlying +instrumentation has changed or is not installed or is not enabled. +This error is used in results from +.BR pmFetch (3) +to indicate these situations. +.TP +.B PM_ERR_IPC +.I "IPC protocol failure" +.br +Generic protocol failure +on a pipe or socket connecting two PCP applications, eg. client\-\c +.BR pmcd , +or client\-\c +.BR pmtime , +or PMDA\-\c +.B pmcd +or +.BR pmlc \- pmlogger . +.TP +.B PM_ERR_TEXT +.I "Oneline or help text is not available" +.br +Set by a PMDA, and passed back to a PCP client, +to indicate that the PMDA is unable to supply the +requested metric or instance domain help text. +.TP +.B PM_ERR_VALUE +.I "Missing metric value(s)" +.br +This error is used for a number of conditions in which the value +of a performance metric is inappropriate for the context in +which it is being used, eg. +.RS +.IP (a) 4n +Bad value for the metric +.B pmcd.timezone +when trying to set the timezone via +.BR pmNewContextZone (3) +for a remote or archive context. +.IP (b) +Attempting to interpolate values for a metric with non-numeric data +type from a PCP archive. +.IP (c) +A bad +.I result +data structure passed to +.BR pmStore (3). +.RE +.TP +.B PM_ERR_NAME +.I "Unknown metric name" +.br +Just what the message says. +.TP +.B PM_ERR_PMID +.I "Unknown or illegal metric identifier" +.br +Just what the message says. +.TP +.B PM_ERR_INDOM +.I "Unknown or illegal instance domain identifier" +.br +A request nominates an instance domain that is unknown +or +.BR PM_INDOM_NULL . +May occur as a consequence of +the instance domain identifier passed by a PCP client to +.BR pmGetInDom (3), +.BR pmLookupInDom (3), +.BR pmNameInDom (3), +.BR pmGetInDomArchive (3), +.BR pmLookupInDomArchive (3), +.BR pmNameInDomArchive (3) +or a request passed from +.BR pmcd (1) +to a PMDA. +.TP +.B PM_ERR_EOF +.I "IPC channel closed" +.br +End of file on a pipe or socket connecting two PCP applications, eg. client\-\c +.BR pmcd , +or client\-\c +.B pmtime +or PMDA\-\c +.BR pmcd. +.TP +.B PM_ERR_NOCONTEXT +.I "Attempt to use an illegal context" +.br +Typically caused by a PCP client that tries to make calls before +calling +.BR pmNewContext (3) +or after calling +.BR pmDestroyContext (3). +.TP +.B PM_ERR_PERMISSION +.I "No permission to perform requested operation" +.br +PCP-specific access controls apply to +.BR pmcd (1) +and +.BR pmlogger (1). +Platform-specific permission errors are returned as +.BR \-EPERM . +.TP +.B PM_ERR_CONV +.I "Impossible value or scale conversion" +.br +Some value conversion requests are illegal, eg. bad debug flag symbolic name +for +.B \-D +option, or asking +.BR pmExtractValue (3) +to translate non-numeric data types to numbers and +.IR vice " " versa . +.TP +.B PM_ERR_TRUNC +.I "Truncation in value conversion" +.br +Some conversion requests to +.BR pmExtractValue (3) +cannot be performed based on the metric types and values involved, +in this case conversion would result in loss of precision. +.TP +.B PM_ERR_SIGN +.I "Negative value in conversion to unsigned" +.br +Some conversion requests to +.BR pmExtractValue (3) +cannot be performed based on the metric types and values involved, +in this case converting a negative value to an unsigned value. +.TP +.B PM_ERR_TYPE +.I "Unknown or illegal metric type" +.br +The metric type is held in the metric descriptor and sometimes +encoded in the metric values returned from a call to +.BR pmFetch (3). +Legal values for the metric type are defined by the +.B PM_TYPE_* +macros in +.BR <pcp/pmapi.h> . +.TP +.B PM_ERR_UNIT +.I "Illegal pmUnits specification" +.br +Some conversion requests to +.BR pmConvScale (3) +cannot be performed due to illegal or incompatible specifications +of the source and destination units. +.TP +.B PM_ERR_PROFILE +.I "Explicit instance identifier(s) required" +.br +Some PMDAs, especially the +.B proc +PMDA, will not return ``all instances'' for a +.BR pmFetch (3) +request due to the cost. The client must explicitly built an instance +profile using +.BR pmAddProfile (3) +and/or +.BR pmDelProfile (3) +before calling +.BR pmFetch (3). +See also the +.B \-F +option to +.BR pminfo (1). +.TP +.B PM_ERR_INST +.I "Unknown or illegal instance identifier" +.br +A request to a PMDA nominates an instance that is unknown. +May occur as a consequence of the profile established prior +to a +.BR pmFetch (3) +call, or an explicit instance name or identifier to +.BR pmLookupInDom (3) +or +.BR pmNameInDom (3). +.TP +.B PM_ERR_MODE +.I "Illegal mode specification" +.br +Illegal +.I mode +argument to +.BR pmSetMode (3). +.TP +.B PM_ERR_PROFILESPEC +.I "NULL pmInDom with non-NULL instlist" +.br +Bad arguments passed from a PCP client to +.BR pmAddProfile (3). +.TP +.B PM_ERR_TOOSMALL +.I "Insufficient elements in list" +.br +Parameter passing error by caller specifying a list with less than +one element to +.BR pmFetch (3), +.BR pmLookupName (3) +or +.BR pmStore (3). +.TP +.B PM_ERR_THREAD +.I "Operation not supported for multi-threaded applications" +.br +As documented in +.BR PMAPI (3) +and elsewhere, some +.B libpcp +routines are intended solely for use from single-threaded applications. +.TP +.B PM_ERR_TOOBIG +.I "Result size exceeded" +.br +Indicates a fatal error in the message (or PDU) passing protocol between +two PCP applications. This is an internal error, and other than +an exotic networking failure, should not occur. +.TP +.B PM_ERR_RESET +.I "PMCD reset or configuration change" +.br +Not used. +.RS +.PP +Refer to +.BR pmFetch (3) +for an alternative mechanism that may be used to notify +a PCP client when +.BR pmcd (1) +has experienced one or more configuration changes since the +last request from the client. Usually these changes involve +a change to the namespace exported via +.B pmcd +and/or changes to the PMDAs under +.BR pmcd 's +control. +.RE +.TP +.B PM_ERR_FAULT +.I "QA fault injected" +.br +Used only for PCP Quality Assurance (QA) testing. +.TP +.B PM_ERR_NYI +.I "Functionality not yet implemented" +.br +Self explanatory and rarely used. +.TP +.B PM_ERR_GENERIC +.I "Generic error, already reported above" +.br +Rarely used, this error may be returned when the error condition +is a consequent of some earlier returned error and a more precise +characterization is not possible. +.SH "CLIENT-PMCD ERRORS" +These errors may occur in the interactions between a PCP client and +.BR pmcd (1) +providing real-time performance data. +.TP +.B PM_ERR_NOAGENT +.I "No PMCD agent for domain of request" +.br +A request sent to +.BR pmcd (1) +requires information from an agent or PMDA that does not exist. +Usually this means the namespace being used by the client application +contains metric names from a previously installed PMDA. +.TP +.B PM_ERR_CONNLIMIT +.I "PMCD connection limit for this host exceeded" +.br +The client connection limit for +.BR pmcd (1) +is controlled by the optional +.B access +controls in +.IR $PCP_PMCDCONF_PATH . +By default there is no limit imposed by the PCP code, and this +error would not be seen. +.TP +.B PM_ERR_AGAIN +.I "Try again. Information not currently available" +.br +Used to notify a PCP client that +the PMDA responsible for delivering the information is temporarily +unavailable. +See also +.BR PM_ERR_PMDANOTREADY . +.TP +.B PM_ERR_NOPROFILE +.I "Missing profile - protocol botch" +.br +Internal error in the communication between a client application +and +.BR pmcd (1) +\- should not occur. +.SH "CLIENT-ARCHIVE ERRORS" +These errors may occur in the interactions between a PCP client and +the library routines that provide historical +performance data from PCP archives created by +.BR pmlogger (1). +.TP +.B PM_ERR_LOGFILE +.I "Missing archive file" +.br +Each PCP archive consists of multiple physical files as described +in +.BR pmlogger (1). +This error occurs when one of the physical files is missing or +cannot be opened for reading. +.TP +.B PM_ERR_EOL +.I "End of PCP archive log" +.br +An attempt is made to read past the end file of the last volume +of a PCP archive, or past the +end of the time window (as specified with a +.B \-T +option) for a PCP archive. +.TP +.B PM_ERR_NOTHOST +.I "Operation requires context with host source of metrics" +.br +Operations involving help text (ie. \c +.BR pmLookupText (3) +and +.BR pmLookupInDomText (3)) +or calls to +.BR pmStore (3) +require a host context and are not supported for PCP archives. +.TP +.B PM_ERR_LOGREC +.I "Corrupted record in a PCP archive log" +.br +PCP archives can become corrupted for a variety of reasons, +but the most common is premature termination of +.BR pmlogger (1) +without flushing its output buffers. +.TP +.B PM_ERR_LABEL +.I "Illegal label record at start of a PCP archive log file" +.br +Each physical file in a PCP archive should begin with a common +label record. This is a special case of +.B PM_ERR_LOGREC +errors. +.TP +.B PM_ERR_NODATA +.I "Empty archive log file" +.br +An empty physical file can never be part of a valid PCP archive +(at least the label record should be present). +This is a special case of +.B PM_ERR_LOGREC +errors. +.TP +.B PM_ERR_NOTARCHIVE +.I "Operation requires context with archive source of metrics" +.br +A call to one of the archive variant routines, i.e. \c +.BR pmFetchArchive (3), +.BR pmGetInDomArchive (3), +.BR pmLookupInDomArchive (3) +or +.BR pmNameInDomArchive (3), +when the current context is not associated with a PCP archive. +.TP +.B PM_ERR_PMID_LOG +.I "Metric not defined in the PCP archive log" +.br +A PCP client has requested information about a metric, +and there is no corresponding information in the PCP archive. +This should not happen for well-behaved PCP clients. +.TP +.B PM_ERR_INDOM_LOG +.I "Instance domain identifier not defined in the PCP archive log" +.br +A PCP client has requested information about an instance domain +for one or more performance metrics, +and there is no corresponding information in the PCP archive. +If the client is using metric descriptors from the archive +to identify the instance domain, this is less likely to happen. +.RS +.PP +Because instance domains may vary over time, clients may +need to use the variant routines +.BR pmGetInDomArchive (3) +or +.BR pmLookupInDomArchive (3) +or +.BR pmNameInDomArchive (3) +to manipulate the union of the instances in an instance domain over the life +of an archive. +.RE +.TP +.B PM_ERR_INST_LOG +.I "Instance identifier not defined in the PCP archive log" +.br +A PCP client has requested information about a specific instance +of a performance metric, +and there is no corresponding information in the PCP archive. +If the client is using instance names from the instance +domain in the archive +(rather than hard-coded instance names) and instance identifiers +from the results returned by +.BR pmFetch (3) +or +.BR pmFetchArchive (3) +this is less likely to happen. +.RS +.PP +Because instance domains may vary over time, clients may +need to use the variant routines +.BR pmLookupInDomArchive (3) +or +.BR pmNameInDomArchive (3) +to manipulate the union of the instances in an instance domain over the life +of an archive. +.RE +.SH "TIME CONTROL ERRORS" +These errors may occur in the interactions between a GUI PCP client and +the time control services provided by +.BR pmtime (1). +.TP +.B PM_ERR_ISCONN +.I "Already Connected" +.br +A PCP client application called +.BR pmTimeConnect (3) +when already connected to a +.BR pmtime (1) +instance. +.TP +.B PM_ERR_NOTCONN +.I "Not Connected" +.br +A PCP client application called one of the time control routines +.BR pmTime* (3) +when not currently connected to any +.BR pmtime (1) +instance. +.TP +.B PM_ERR_NEEDPORT +.I "A non-null port name is required" +.br +If a shared +.BR pmtime (1) +instance is being created +the +.I port +argument to +.BR pmTimeConnect (3) +must not be invalid. +.SH "NAMESPACE ERRORS" +These errors may occur in the processing of PCP namespace operations. +A PCP namespace, see +.BR pmns (5), +provides the external +names and the internal identifiers for the available performance metrics. +.TP +.B PM_ERR_NONLEAF +.I "Metric name is not a leaf in PMNS" +.br +The metric name passed to +.BR pmLookupName (3) +names a non-terminal path in the namespace, i.e. a group of metrics +rather than a single metric. +.TP +.B PM_ERR_DUPPMNS +.I "Attempt to reload the PMNS" +.br +When using an explicit local namespace, it is illegal to call +either of +.BR pmLoadNameSpace (3) +or +.BR pmLoadASCIINameSpace (3) +more than once. +.TP +.B PM_ERR_PMNS +.I "Problems parsing PMNS definitions" +.br +Only occurs when an ASCII namespace is explicitly loaded. +.TP +.B PM_ERR_NOPMNS +.I "PMNS not accessible" +.br +Only occurs when an ASCII namespace is explicitly loaded. +.SH "PMCD-PMDA ERRORS" +These error codes are used in the interactions between +.BR pmcd (1) +and the PMDAs that provide the performance data. +.TP +.B PM_ERR_PMDANOTREADY +.I "PMDA is not yet ready to respond to requests" +.br +Some PMDAs have long initialization or reset times, and will respond +to +.BR pmcd (1) +with this error if they are busy at the moment. This error translates +to +.B PM_ERR_AGAIN +for the PCP client who made the request to +.BR pmcd +which caused the initial request to the PMDA. +At some later time the PMDA will inform +.B pmcd +(see +.BR PM_ERR_PMDAREADY ) +that it is now ready to process requests, and client +requests will begin to succeed. +.TP +.B PM_ERR_PMDAREADY +.I "PMDA is now responsive to requests" +.br +Used by PMDAs to asynchronously inform +.BR pmcd (1) +that they are now willing to resume processing requests. +See also +.BR PM_ERR_PMDANOTREADY . +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.I /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). +Values for these variables may be obtained programmatically +using the +.BR pmGetConfig (3) +function. +.SH SEE ALSO +.BR pmerr (1), +.BR PMAPI (3), +.BR pmErrStr (3), +.BR pmGetConfig (3), +.BR pcp.conf (5) +and +.BR pcp.env (5). diff --git a/man/man3/pmaddprofile.3 b/man/man3/pmaddprofile.3 new file mode 100644 index 0000000..457e4ae --- /dev/null +++ b/man/man3/pmaddprofile.3 @@ -0,0 +1,112 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000-2004 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMADDPROFILE 3 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmAddProfile\f1 \- add instance(s) to the current PMAPI instance profile +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.sp +int pmAddProfile(pmInDom \fIindom\fP, int \fInuminst\fP, int *\fIinstlist\fP); +.sp +cc ... \-lpcp +.ft 1 +.SH DESCRIPTION +.de CW +.ie t \f(CW\\$1\f1\\$2 +.el \fI\\$1\f1\\$2 +.. +The set of instances for performance metrics returned from a +.BR pmFetch (3) +call may be filtered or restricted using an instance profile. +There is one instance profile for each context the application +creates at the Performance Metrics Application Programming Interface +.RB ( PMAPI (3)), +and each instance profile may include instances from one or more +instance domains (see +.BR pmLookupDesc (3)). +.PP +.B pmAddProfile +may be used to +add new instance specifications to the instance profile of the current +PMAPI context. +.PP +In the simplest variant, the list of instances identified by the +.I instlist +argument for the +.I indom +instance domain are added to the instance profile. +The list of instance +identifiers contains +.I numinst +values. +.PP +The +.I indom +value would normally be extracted from a call to +.BR pmLookupDesc (3) +for a particular performance metric, and the instances in +.I instlist +would typically be determined by calls to +.BR pmGetInDom (3) +or +.BR pmLookupInDom (3). +.PP +To select all instances in all instance domains, use + +.in 1.0i +.nf +.ft CW +pmAddProfile(PM_INDOM_NULL, 0, (int *)0) +.ft +.fi +.in + +This is the only case where +.I indom +may be equal to +.BR PM_INDOM_NULL . +If +.I numinst +is zero, or +.I instlist +is NULL, then all instances in +.I indom +are selected. +.SH SEE ALSO +.BR PMAPI (3), +.BR pmDelProfile (3), +.BR pmFetch (3), +.BR pmGetInDom (3), +.BR pmLookupDesc (3), +.BR pmLookupInDom (3), +.BR pmNewContext (3), +.BR pmUseContext (3) +and +.BR pmWhichContext (3). +.SH DIAGNOSTICS +.IP \f3PM_ERR_PROFILESPEC\f1 +.I indom +was +.B PM_INDOM_NULL +and +.I instlist +was not empty +.SH CAVEAT +It is possible to add non-existent instance domains and non-existent instances +to an instance profile. None of the routines that use the instance profile +will ever issue an error if you do this. The cost of checking, when checking +is possible, outweighs any benefits. diff --git a/man/man3/pmaf.3 b/man/man3/pmaf.3 new file mode 100644 index 0000000..fc91906 --- /dev/null +++ b/man/man3/pmaf.3 @@ -0,0 +1,152 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000-2004 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMAF 3 "PCP" "Performance Co-Pilot" +.SH NAME +\f3__pmAFregister\f1, +\f3__pmAFunregister\f1, +\f3__pmAFblock\f1, +\f3__pmAFunblock\f1, +\f3__pmAFisempty\f1 \- event queue services for periodic asynchronous callbacks +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.br +#include <pcp/impl.h> +.sp +.ad l +.hy 0 +.in +8n +.ti -8n +int __pmAFregister(const struct timeval *\fIdelta\fP, void *\fIdata\fP, void\ (*\fIfunc\fP)(int,\ void *)); +.br +.in +.hy +.ad +int __pmAFunregister(int \fIafid\fP); +.br +void __pmAFblock(void); +.br +void __pmAFunblock(void); +.br +int __pmAFisempty(void); +.sp +cc ... \-lpcp +.ft 1 +.SH DESCRIPTION +The routines implement an event queue and callback framework that supports +periodic evaluation of a series of events with varying frequencies +for Performance Co-Pilot (PCP) applications. +.P +The +.BR pmlogger (1) +application, the +.BR pmdatrace (1) +PMDA and the +.BR pmdahotproc (1) +PMDA are the principal users of these services. +.P +An event is registered by calling +.BR __pmAFregister , +and on success the return value is an event number greater than zero. +The event has associated event data identified by the opaque pointer +.IR data . +The event will occur with frequency +.IR delta +(the first instance will be +.I delta +after the current time when the event is registered), +and each time the event occurs the function +.I func +will be called with the event number and the event data as arguments. +.P +Once the event occurs and the callback has been executed, the event +will be rescheduled for +.I delta +into the future, except +if all the fields of +.I delta +are zero, in which case +the event will not be rescheduled +(a ``one trip'' event). +.P +Internally, events are processed serially so there is no +possibility of nested callbacks or re-entrant callbacks from the +event management routines. +.P +Given an event number +.IR afid , +.B __pmAFunregister +will permanently remove the corresponding entry from the event queue. +.P +To control the event queue processing, +.B __pmAFblock +and +.B __pmAFunblock +may be used to explicitly block and unblock the dispatch of events. +This is most useful when the caller wishes to set up a number of +events via +.B __pmAFregister +and complete the registration phase before the first +event callback occurs. +.P +A call to +.B __pmAFisempty +returns 1 or 0 depending on whether the event queue is empty or not. +.SH SEE ALSO +.BR PMAPI (3) +.SH DIAGNOSTICS +.PP +.B __pmAFregister +and +.B __pmAFunregister +return values less than zero in the case of an error. These values +are PCP error codes, and may be used to produce error messages via +.BR pmErrStr (3). +.P +The routines support the standard PCP debug tracing, and the value +.B DBG_TRACE_AF +(or +.B "\-D af" +on the command line) +will produce diagnostics on standard error that trace the enqueueing +and execution of events. +.SH CAVEATS +These routines rely on +.BR setitimer (2) +and manipulate the handling of +.B SIGALRM +signals, and hence are probably ill-suited for applications that +require direct and concurrent access to these services and resources. +.P +If the callback functions are slow, or delayed, it is possible that +the event scheduling could fall behind and never catchup. When this +begins to happen, events are silently skipped and rescheduled at the earliest +possible time on the future according to the fixed schedule defined +by the time of the call to +.B __pmAFregister +and the value of the +.I delta +argument to +.BR __pmAFregister . +.P +In addition, the semantics of the interval timer(s) and the global +state needed to support these services demand that applications +calling these routines must do so from a single thread. +This restriction is enforced at the +.BR PMAPI (3), +where routines may return the error code +.B PM_ERR_THREAD +if the library detects calls from more than one thread. diff --git a/man/man3/pmafm.3 b/man/man3/pmafm.3 new file mode 100644 index 0000000..6d0c122 --- /dev/null +++ b/man/man3/pmafm.3 @@ -0,0 +1,479 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 1998-2008 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMAFM 3 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmafm\f1, +\f3pmRecordSetup\f1, +\f3pmRecordAddHost\f1, +\f3pmRecordControl\f1 \- record mode support for PMAPI clients +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmafm.h> +.sp +.ad l +.hy 0 +.in +8n +.ti -8n +FILE *pmRecordSetup(const char *\fIfolio\fP, const char *\fIcreator\fP, int\ \fIreplay\fP); +.br +.ti -8n +int pmRecordAddHost(const char *\fIhost\fP, int \fIisdefault\fP, pmRecordHost\ **\fIrhp\fP); +.br +.ti -8n +int pmRecordControl(pmRecordHost *\fIrhp\fP, int \fIrequest\fP, const\ char\ *\fIoptions\fP); +.sp +.in +.hy +.ad +cc ... \-lpcp_gui +.ft 1 +.SH DESCRIPTION +These routines may be used to create a Performance Co-Pilot (PCP) +archive ``on the fly'' to +support ``record mode'' services for PMAPI client applications. +.PP +Each record mode ``session'' involves one or more +PCP archive logs each created using a dedicated +.BR pmlogger (1) +process, with an overall Archive Folio format as understood by +.BR pmafm (1), +to name and collect all of the archive logs associated with +a single recording session. +.PP +The +.I pmRecordHost +structure is used to maintain state information between the +creator of the recording session and the associated +.BR pmlogger +process(es). The structure is defined as: +.sp 0.5v +.ft CW +.nf +.in +0.25i +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; +.in -0.25i +.fi +.ft R +.PP +The routines are used in combination to create a recording session +as follows. +.IP 1. 4n +Call +.B pmRecordSetup +to establish a new recording session. A new Archive Folio will be +created using the name +.IR folio ; +if the file or directory +.I folio +already exists, or the file +.I folio +cannot be created, this is an error. +The application that is creating the session is identified by +.I creator +(most often this would be the same as the global PMAPI application name, +.IR pmProgname ). +If the application knows how to create its own configuration file to replay +the recorded session, then +.I replay +should be non-zero. +.RS +.PP +.B pmRecordSetup +returns a +.I stdio +stream onto +which the application should write the text of the required +replay configuration file, if any. +.RE +.IP 2. +For each +.I host +that is to be included in the recording session, call +.BR pmRecordAddHost . +A new +.I pmRecordHost +structure is returned via +.IR rhp . +It is assumed that +.BR pmcd (1) +is running on +.I host +as this is how +.BR pmlogger (1) +will retrieve the required performance metrics. +.RS +.PP +If this +.I host +is the default host for this recording session, then +.I isdefault +should be non-zero. This will ensure that the corresponding archive +appears first in the PCP archive folio, and hence the tools used +to replay the archive folio will make the correct determination of the +archive associated with the default host. +At most one +.I host +per recording session may be nominated as the default host. +.PP +The calling application should +write the desired +.B pmlogger +configuration onto the +.I stdio +stream returned via the +.I f_config +field in the +.I pmRecordHost +structure. +.RE +.IP 3. +Optionally add arguments to the command line that will be used +to launch +.BR pmlogger (1) +by calling +.B pmRecordControl +with a +.I request +of +.BR PM_REC_SETARG . +The argument is passed via +.I options +and one call to +.B pmRecordControl +is required for each distinct argument. +.RS +.PP +An argument may be added for a particular +.B pmlogger +instance +identified by +.IR rhp , +or if the +.I rhp +argument +is NULL the argument is added for all +.B pmlogger +instances that will be launched in the current recording session. +.PP +Independent of any calls to +.B pmRecordControl +with a +.I request +of +.BR PM_REC_SETARG , +each +.B pmlogger +instance will automatically be launched with the following arguments: +.BR \-c , +.BR \-h , +.BR \-l , +.B \-x +and the basename for the PCP archive log. +.RE +.IP 4. +To commence the recording session, call +.B pmRecordControl +with a +.I request +of +.BR PM_REC_ON , +and +.I rhp +must be NULL. +This will launch one +.BR pmlogger (1) +process for each host in the recording session, +and initialize the +.IR fd_ipc , +.IR logfile , +.I pid +and +.I status +fields in the associated +.I pmRecordHost +structure(s). +.IP 5. +To terminate a +.B pmlogger +instance +identified by +.IR rhp , +call +.B pmRecordControl +with a +.I request +of +.BR PM_REC_OFF . +If the +.I rhp +argument to +.B pmRecordControl +is NULL, the termination request is broadcast to all +.B pmlogger +processes in the current recording session. +.RS +.PP +An informative dialog is generated directly by each +.B pmlogger +process and hence note the comments on the disposition of output from +.B pmlogger +below. +.PP +Alternatively, +.B pmlogger +can be started with options to limit the duration of logging, e.g. the +.B \-T +or +.B \-s +arguments, in which case there is no need to call +.B pmRecordControl +with a +.I request +of +.B PM_REC_OFF +and no dialog is generated. +.RE +.IP 6. +To display the current status of the +.B pmlogger +instance identified by +.IR rhp , +call +.B pmRecordControl +with a +.I request +of +.BR PM_REC_STATUS . +If the +.I rhp +argument to +.B pmRecordControl +is NULL, the status request is broadcast to all +.B pmlogger +processes in the current recording session. +.RS +.PP +The display is generated directly by each +.B pmlogger +process and hence note the comments on the disposition of output from +.B pmlogger +below. +.RE +.IP 7. +To detach a +.B pmlogger +instance identified by +.IR rhp +and allow it to continue independent of +the application that launched the recording session, call +.B pmRecordControl +with a +.I request +of +.BR PM_REC_DETACH . +If the +.I rhp +argument to +.B pmRecordControl +is NULL, the detach request is broadcast to all +.B pmlogger +processes in the current recording session. +.RS +.PP +An informative dialog is generated directly by each +.B pmlogger +process and hence note the comments on the disposition of output from +.B pmlogger +below. +.RE +.PP +The calling application should not close any of the returned +.I stdio +streams; this will be done by +.B pmRecordControl +when recording is commenced. +.PP +Once +.B pmlogger +has been started for a recording session, then +.B pmlogger +will assume responsibility for any dialog with the user in the event +that the application that launched the recording session should +exit, particularly without terminating the recording session. +.PP +By default, information and dialogs from +.B pmlogger +will be displayed using +.BR pmquery (1) +on the assumption that most applications wishing to launch +a recording session are GUI-based. In the event that +.B pmquery +fails to display the information (for example, because the +.B DISPLAY +environment variable is not set), +.B pmlogger +will write on its own +.I stderr +stream (\c +.B not +the +.I stderr +stream of the launching process); +the output will be assigned to the +.I XXXXXX.host.\fBlog\fP +file described in the FILES section below. +For convenience, the full pathname to this file is provided via the +.I logfile +field in the +.I pmRecordHost +structure. +.PP +If the +.I options +argument to +.B pmRecordControl +is not NULL, this string may be +used to pass additional arguments to +.BR pmquery (1) +in those cases where a dialog is to be displayed. One use of this +capability would be to +provide a +.B \-geometry +string to control the placement of the dialog. +.PP +Premature termination of a launched +.B pmlogger +process may be determined using the +.I pmRecordHost +structure, +by calling +.BR select (2) +on the +.I fd_ipc +field +or polling the +.I status +field that will contain the termination status from +.BR waitpid (2) +if known, else \-1. +.SH SEE ALSO +.BR pmafm (1), +.BR pmlogger (1), +.BR pmquery (1) +and +.BR PMAPI (3). +.SH FILES +These routines create a number of files in the +.B "same directory" +as the +.I folio +file named in the call to +.BR pmRecordSetup . +In all cases, the ``XXXXXX'' component is the result of +calling +.BR mktemp (3). +.TP 10 +.I XXXXXX +If +.I replay +is non-zero, this is the creator's replay configuration file, else +an empty control file, used to guarantee uniqueness. +.PD 0 +.TP +.I folio +The PCP Archive Folio, suitable for use with +.BR pmafm (1). +.TP +.I XXXXXX.host.\fBconfig\fP +The +.BR pmlogger (1) +configuration for each +.I host +\- if the same +.I host +is used in different calls to +.B pmRecordAddHost +within the same recording session +then one of the letters ``a'' through ``z'' will +be appended to the ``XXXXXX'' part of all associated file names to ensure +uniqueness. +.TP +.I XXXXXX.host.\fBlog\fP +.I stdout +and +.I stderr +for the +.BR pmlogger (1) +instance for each +.IR host . +.TP +.I XXXXXX.host.\fR{\fB0\fP,\fBmeta\fP,\fBindex\fP} +The files comprising a single PCP archive for each +.IR host . +.SH DIAGNOSTICS +.PD +.PP +.B pmRecordSetup +may return +.B NULL +in the event of an error. +Check +.I errno +for the real cause, but the value +.B EINVAL +typically means that the order of calls to these routines is +not correct (there is obvious state associated with the current +recording session that is maintained across calls to these routines). +For example +the following calls would produce this +.B EINVAL +error; +calling +.B pmRecordControl +before calling +.B pmRecordAddHost +at least once, or calling +.B pmRecordAddHost +before calling +.BR pmRecordSetup . +.PP +.B pmRecordControl +and +.B pmRecordAddHost +both return 0 on success, else a value less than 0 suitable for +decoding with +.BR pmErrStr (3) +on failure. +The value +.B \-EINVAL +has the same interpretation as +.I errno +being set to +.B EINVAL +as described above. +.PP +.B pmRecordControl +will return +.B PM_ERR_IPC +if the associated +.B pmlogger +process has already exited. diff --git a/man/man3/pmapi.3 b/man/man3/pmapi.3 new file mode 100644 index 0000000..0c3a35c --- /dev/null +++ b/man/man3/pmapi.3 @@ -0,0 +1,455 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMAPI 3 "PCP" "Performance Co-Pilot" +.SH NAME +\f3PMAPI\f1 \- introduction to the Performance Metrics Application Programming Interface +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.sp +.ft 1 +\& ... assorted routines ... +.ft 3 +.sp +cc ... \-lpcp +.ft 1 +.SH DESCRIPTION +.de CW +.ie t \f(CW\\$1\f1\\$2 +.el \fI\\$1\f1\\$2 +.. +.\" add in the -me strings for super and subscripts +.ie n \{\ +. ds [ \u\x'-0.25v' +. ds ] \d +. ds { \d\x'0.25v' +. ds } \u +.\} +.el \{\ +. ds [ \v'-0.4m'\x'-0.2m'\s-3 +. ds ] \s0\v'0.4m' +. ds { \v'0.4m'\x'0.2m'\s-3 +. ds } \s0\v'-0.4m' +.\} +Within the framework of the Performance Co-Pilot (PCP), client +applications are developed using the +Performance Metrics Application Programming Interface (PMAPI) that +defines a procedural interface with services suited to the development +of applications with a particular interest in performance metrics. +.PP +This description presents an overview of the PMAPI and the +context in which PMAPI applications are run. +The PMAPI is more fully described in the +.IR "Performance Co-Pilot Programmer's Guide" , +and the manual pages for the individual PMAPI routines. +.SH "PERFORMANCE METRICS \- NAMES AND IDENTIFIERS" +For a description of the Performance Metrics Name Space (PMNS) +and associated terms and concepts, +see +.BR PCPIntro (1). +.PP +Not all PMIDs need be represented in the PMNS of +every application. +For example, an application which monitors disk +traffic will likely use a name space which references only the PMIDs +for I/O statistics. +.PP +Applications which use the PMAPI may have independent +versions of a PMNS, constructed from an initialization file when the +application starts; see +.BR pmLoadASCIINameSpace (3), +.BR pmLoadNameSpace (3), +and +.BR pmns (5). +.PP +Internally (below the PMAPI) the implementation of the +Performance Metrics Collection System +(PMCS) uses only the PMIDs, and a PMNS +provides an external mapping from a hierarchic taxonomy of names to +PMIDs that is +convenient in the context of a particular system or particular use of +the PMAPI. +For the applications programmer, +the routines +.BR pmLookupName (3) +and +.BR pmNameID (3) +translate between names in a PMNS and PMIDs, and vice versa. +The PMNS may be traversed using +.BR pmGetChildren (3). +.SH "PMAPI CONTEXT" +An application using the PMAPI may manipulate several concurrent contexts, +each associated with a source of performance metrics, e.g. \c +.BR pmcd (1) +on some host, or an archive log of performance metrics as created by +.BR pmlogger (1). +.PP +Contexts are identified by a ``handle'', a small integer value that is returned +when the context is created; see +.BR pmNewContext (3) +and +.BR pmDupContext (3). +Some PMAPI functions require an explicit ``handle'' to identify +the correct context, but more commonly the PMAPI function is +executed in the ``current'' context. +The current context may be discovered using +.BR pmWhichContext (3) +and changed using +.BR pmUseContext (3). +.PP +If a PMAPI context has not been explicitly established +(or the previous current context has been closed using +.BR pmDestroyContext (3)) +then the current PMAPI context is undefined. +.PP +In addition to the source of the performance metrics, the context +also includes the instance profile and collection time (both described below) +which controls +how much information is returned, and when the information was collected. +.SH "INSTANCE DOMAINS" +When performance metric values are returned across the PMAPI to a +requesting application, there may be more than one value for a +particular metric. +Multiple values, or +.BR instances , +for a single metric +are typically the result of instrumentation being implemented for each +instance of a set of similar components or services in a system, e.g. +independent counts for each CPU, or each process, or each disk, or each +system call type, etc. +This multiplicity of values is not enumerated in +the name space but rather, when performance metrics are delivered +across the PMAPI by +.BR pmFetch (3), +the format of the result accommodates values for one +or more instances, with an instance-value pair +encoding the metric value for a particular +instance. +.PP +The instances are identified by an internal identifier assigned +by the agent responsible for instantiating the values for the +associated performance metric. +Each instance identifier has a corresponding external instance identifier +name (an ASCII string). +The routines +.BR pmGetInDom (3), +.BR pmLookupInDom (3) +and +.BR pmNameInDom (3) +may be used to enumerate all instance identifiers, and to +translate between internal and external instance +identifiers. +.PP +All of the instance identifiers for a particular performance metric +are collectively known as an instance domain. +Multiple performance metrics may share the same instance domain. +.PP +If only one instance is ever available for a particular performance +metric, the instance identifier +in the result from +.BR pmFetch (3) +assumes the special value +.B PM_IN_NULL +and may be ignored by the +application, and only one instance-value pair appears in the result +for that metric. +Under these circumstances, the associated instance domain (as returned +via +.BR pmLookupDesc (3)) +is set to +.B PM_INDOM_NULL +to indicate that values for this metric are singular. +.PP +The difficult issue of +transient performance metrics (e.g. per-filesystem information, hot-plug +replaceable hardware modules, etc.) means that repeated requests for +the same PMID may return different numbers of values, and/or some +changes in the particular instance identifiers returned. +This means +applications need to be aware that metric instantiation is guaranteed +to be valid at the time of collection only. +Similar rules apply to the +transient semantics of the associated metric values. +In general +however, it is expected that the bulk of the performance metrics will +have instantiation semantics that are fixed over the execution +life-time of any PMAPI client. +.SH "THE TYPE OF METRIC VALUES" +The PMAPI supports a wide range of format and type encodings for +the values of performance metrics, namely signed and unsigned integers, +floating point numbers, 32-bit and 64-bit encodings of all of the above, +ASCII strings (C-style, NULL byte terminated), and arbitrary aggregates of +binary data. +.PP +The +.CW type +field in the +.CW pmDesc +structure returned by +.BR pmLookupDesc (3) +identifies the format and type of the values for a particular +performance metric within a particular PMAPI context. +.PP +Note that the encoding of values for a particular performance metric +may be different for different PMAPI contexts, due to differences +in the underlying implementation for different contexts. +However it is expected that the vast majority of performance metrics +will have consistent value encoding across all versions of all +implementations, and hence across all PMAPI contexts. +.PP +The PMAPI supports routines to automate the handling +of the various value formats and types, particularly for +the common case where conversion to a canonical format is +desired, see +.BR pmExtractValue (3) +and +.BR pmPrintValue (3). +.SH "THE DIMENSIONALITY AND SCALE OF METRIC VALUES" +Independent of how the value is encoded, the +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. +The dimensionality is defined by a power, or index, in +each of 3 orthogonal dimensions, namely Space, Time and Count +(or Events, which are dimensionless). +For example I/O throughput might be represented as +Space/Time, while the +running total of system calls is Count, memory allocation is Space and average +service time is Time/Count. +In each dimension there are a number +of common scale values that may be used to better encode ranges that might +otherwise exhaust the precision of a 32-bit value. +This information is encoded +in the +.CW pmUnits +structure which is embedded in the +.CW pmDesc +structure returned from +.BR pmLookupDesc (3). +.PP +The routine +.BR pmConvScale (3) +is provided to convert values in +conjunction with the +.CW pmUnits +structures that defines the dimensionality and scale of the values for a +particular performance metric as returned from +.BR pmFetch (3), +and the desired dimensionality and scale of +the value the PMAPI client wishes to manipulate. +.SH "INSTANCE PROFILE" +The set of instances for performance metrics returned from a +.BR pmFetch (3) +call may be filtered or restricted using an instance profile. +There is one instance profile for each PMAPI context the application +creates, +and each instance profile may include instances from one or more +instance domains. +.PP +The routines +.BR pmAddProfile (3) +and +.BR pmDelProfile (3) +may be used to dynamically adjust the instance profile. +.SH "COLLECTION TIME" +For each set of values for performance metrics returned +via +.BR pmFetch (3) +there is an associated ``timestamp'' +that serves to identify when the performance metric +values were collected; for metrics being delivered from +a real-time source (i.e. \c +.BR pmcd (1) +on some host) this would typically be not long before they +were exported across the PMAPI, and for metrics being delivered +from an archive log, this would be the time when the metrics +were written into the archive log. +.PP +There is an issue here of exactly +when individual metrics may have been collected, especially given +their origin in potentially different Performance Metric Domains, and +variability in the metric updating frequency at the lowest level of the +Performance Metric Domain. +The PMCS opts for the pragmatic approach, +in which the PMAPI implementation undertakes to return all of the +metrics with values accurate as of the timestamp, to the best of our +ability. +The belief is that the inaccuracy this introduces is small, +and the additional burden of accurate individual timestamping for each +returned metric value is neither warranted nor practical (from an +implementation viewpoint). +.PP +Of course, in the case of collection of +metrics from multiple hosts the PMAPI client must assume the +sanity of the timestamps is constrained by the extent to which clock +synchronization protocols are implemented across the network. +.PP +A PMAPI application may call +.BR pmSetMode (3) +to vary the requested collection time, e.g. to rescan performance +metrics values from the recent past, or to ``fast-forward'' through +an archive log. +.SH "GENERAL ISSUES OF PMAPI PROGRAMMING STYLE" +Across the PMAPI, all arguments and results involving a +``list of something'' are declared to be arrays with an associated argument or +function value to identify the number of elements in the list. +This has been done to avoid both the +.BR varargs (3) +approach and sentinel-terminated lists. +.PP +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 will assume the result argument is of +an appropriate size. +Where a result is of variable size and that size +cannot be known in advance (e.g. for +.BR pmGetChildren (3), +.BR pmGetInDom (3), +.BR pmNameInDom (3), +.BR pmNameID (3), +.BR pmLookupText (3) +and +.BR pmFetch (3)) +the PMAPI implementation uses a range of dynamic +allocation schemes in the called routine, with the caller +responsible for subsequently releasing the storage when +no longer required. +In some cases this simply involves calls to +.BR free (3C), +but in others (most notably for the result from +.BR pmFetch (3)), +special routines (e.g. \c +.BR pmFreeResult (3)) +should be used to release the storage. +.PP +As a general rule, if the called routine returns +an error status then no allocation will have been +done, and any pointer to a variable sized result is undefined. +.SH DIAGNOSTICS +Where error conditions may arise, the functions that comprise the PMAPI conform to a single, simple +error notification scheme, as follows; +.IP + 3n +the function returns an integer +.IP + 3n +values >= 0 indicate no error, and perhaps some positive status, +e.g. the number of things really processed +.IP + 3n +values < 0 indicate an error, with a global table of error conditions and error messages +.PP +The PMAPI routine +.BR pmErrStr (3) +translates error conditions into error messages. +By convention, the small negative +values are assumed to be negated versions of the Unix error codes as defined +in +.B <errno.h> +and the strings returned are as per +.BR strerror (3C). +The larger, negative error codes are PMAPI error conditions. +.PP +One error, common to all PMAPI routines that interact with +.BR pmcd (1) +on some host is +.BR PM_ERR_IPC , +which indicates the communication link to +.BR pmcd (1) +has been lost. +.SH "MULTI-THREADED APPLICATIONS" +The original design for PCP was based around single-threaded applications, or +more strictly applications in which only one thread was ever expected to +call the PCP libraries. +This restriction has been relaxed for +.B libpcp +to allow the most common PMAPI routines to be safely called from any +thread in a multi-threaded application. +.PP +However the following groups of functions and services in +.B libpcp +are still restricted to being called from a single-thread, and this is enforced +by returning +.B PM_ERR_THREAD +when an attempt to call the routines in each group from more than one +thread is detected. +.TP 4n +1. +Any use of a +.B PM_CONTEXT_LOCAL +context, as the DSO PMDAs that are called directly from +.B libpcp +may not be thread-safe. +.TP 4n +2. +The interval timer services use global state with semantics that demand +it is only used in the context of a single thread, so +.BR __pmAFregister (3), +.BR __pmAFunregister (3), +.BR __pmAFblock (3), +.B __pmAFunblock (3) +and +.BR __pmAFisempty (3). +.TP 4n +3. +The following (undocumented) access control manipulation +routines that are principally intended +for single-threaded applications: +.BR __pmAccAddOp , +.BR __pmAccSaveHosts , +.BR __pmAccRestoreHosts , +.BR __pmAccFreeSavedHosts , +.BR __pmAccAddHost , +.BR __pmAccAddClient , +.B __pmAccDelClient +and +.BR __pmAccDumpHosts . +.TP 4n +4. +The following (undocumented) routines that identify +.I pmlogger +control ports and are principally intended +for single-threaded applications: +.B __pmLogFindPort +and +.BR __pmLogFindLocalPorts . +.SH "PCP ENVIRONMENT" +Most environment variables are described in +.BR PCPIntro (1). +In addition, +environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.I /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). +Values for these variables may be obtained programmatically +using the +.BR pmGetConfig (3) +function. +.SH SEE ALSO +.BR PCPIntro (1), +.BR PCPIntro (3), +.BR PMAPI (3), +.BR pmda (3), +.BR pmGetConfig (3), +.BR pcp.conf (5) +and +.BR pcp.env (5). diff --git a/man/man3/pmatomstr.3 b/man/man3/pmatomstr.3 new file mode 100644 index 0000000..b5fa298 --- /dev/null +++ b/man/man3/pmatomstr.3 @@ -0,0 +1,119 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMATOMSTR 3 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmAtomStr\f1, +\f3pmAtomStr_r\f1 \- convert a performance metric value into a string +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.sp +const char *pmAtomStr(const pmAtomValue *\fIavp\fP, int \fItype\fP); +.br +char *pmAtomStr_r(const pmAtomValue *\fIavp\fP, int \fItype\fP, char *\fIbuf\fP, int \fIbuflen\fP); +.sp +cc ... \-lpcp +.ft 1 +.SH DESCRIPTION +.de CW +.ie t \f(CW\\$1\f1\\$2 +.el \fI\\$1\f1\\$2 +.. +All performance metric values may be encoded in a +.CW pmAtomValue +union, defined as follows; +.PP +.ft CW +.nf +.in +0.5i +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 */ + pmValueBlock *vbp; /* pmValueBlock ptr */ +} pmAtomValue; +.in +.fi +.ft 1 +.PP +Given the performance metric value pointed to by +.IR avp , +and a performance metric type defined by +.IR type , +.B pmAtomStr +will generate the corresponding metric value as a string, +suitable for diagnostic or report output. +The +.B pmAtomStr_r +function does the same, but stores the result in a user-supplied buffer +.I buf +of length +.IR buflen , +which should have room for at least 80 bytes. +.PP +The value for +.I type +is typically extracted from a +.CW pmDesc +structure, following a call to +.BR pmLookupDesc (3) +for a particular performance metric. +.PP +If the +.I type +is +.B PM_TYPE_STRING +values longer than 38 characters will be truncated after 34 characters, +and truncation shown with ellipsis ``...'' at the end of the value. +.PP +If the +.I type +is +.B PM_TYPE_AGGREGATE +then up to the first three 32-bit words are displayed as hexadecimal values. +.PP +If the +.I type +is +.B PM_TYPE_EVENT +then a summary of the number of event records found in the value +is generated. +.PP +The return value from +.B pmAtomStr +is held in a single static buffer, so +the returned value is only valid until the next call +to +.BR pmAtomStr . +.SH NOTES +.B pmAtomStr +returns a pointer to a static buffer and hence is not thread-safe. +Multi-threaded applications should use +.B pmAtomStr_r +instead. +.SH SEE ALSO +.BR PMAPI (3), +.BR pmConvScale (3), +.BR pmExtractValue (3), +.BR pmLookupDesc (3), +.BR pmPrintValue (3), +.BR pmTypeStr (3) +and +.BR pmUnitsStr (3). diff --git a/man/man3/pmconnectlogger.3 b/man/man3/pmconnectlogger.3 new file mode 100644 index 0000000..e29ded1 --- /dev/null +++ b/man/man3/pmconnectlogger.3 @@ -0,0 +1,106 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000-2004 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMCONNECTLOGGER 3 "PCP" "Performance Co-Pilot" +.SH NAME +\f3__pmConnectLogger\f1 \- connect to a performance metrics logger control port +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.br +#include <pcp/impl.h> +.br +.sp +int __pmConnectLogger(const char *\fIhostname\fP, int \fIpid\fP); +.sp +cc ... \-lpcp +.ft 1 +.SH DESCRIPTION +.de CW +.ie t \f(CW\\$1\fR\\$2 +.el \fI\\$1\fR\\$2 +.. +Each instance of the Performance Co-Pilot (PCP) archive logger program +.BR pmlogger (1) +supports a control port on which +.BR __pmControlLog (3) +requests are received, and responses sent. +Optionally, the +.BR pmlogger (1) +instance may be designated the ``primary'' logger. +.PP +.B __pmConnectLogger +may be used to establish a control port connection to the +.BR pmlogger (1) +instance identified by process id +.I pid +on the host +.IR hostname . +.PP +One special case is supported; for the reserved +.I pid +value of +.B PM_LOG_CONTROL_PORT +the requested connection is to the +control port for the ``primary'' logger, whatever its process +id might be. +.PP +On success, +.B __pmConnectLogger +returns a non-negative integer, that is a file descriptor that may be used +in subsequent communication with the +.BR pmlogger (1) +instance, e.g. for +.BR __pmControlLog (3). +.PP +As the control port to +.BR pmlogger (1) +is not mulitplexed, applications using +.B __pmConnectLogger +should use +.BR close (2) +to terminate the connection to +.BR pmlogger (1) +as soon as they have finished communicating. +.PP +If the application connects, and the +.BR pmlogger (1) +instance subsequently terminates, e.g. \c +because the associated +.BR pmcd (1) +instance is terminated, the application will have to explicitly +re-establish connection to a re-started +.BR pmlogger (1) +instance by calling +.B __pmConnectLogger +again. +.SH SEE ALSO +.BR pmcd (1), +.BR pmlc (1), +.BR pmlogger (1), +.BR PMAPI (3) +and +.BR __pmControlLog (3). +.SH DIAGNOSTICS +.IP \f3PM_ERR_PERMISSION\f1 +no permission to connect to the specified +.BR pmlogger (1) +instance +.IP \f3\-ECONNREFUSED\f1 +the designated +.BR pmlogger (1) +instance does not exist +.IP \f3\-EEADDRINUSE\f1 +the requested control port is already in use diff --git a/man/man3/pmcontrollog.3 b/man/man3/pmcontrollog.3 new file mode 100644 index 0000000..820de32 --- /dev/null +++ b/man/man3/pmcontrollog.3 @@ -0,0 +1,286 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000-2004 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMCONTROLLOG 3 "PCP" "Performance Co-Pilot" +.SH NAME +\f3__pmControlLog\f1 \- enable, disable or enquire about logging of performance +metrics +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.br +#include <pcp/impl.h> +.sp +.ad l +.hy 0 +.in +8n +.ti -8n +int __pmControlLog(int \fIfd\fP, const pmResult *\fIrequest\fP, int\ \fIcontrol\fP, int\ \fIstate\fP, int\ \fIdelta\fP, pmResult\ **\fIstatus\fP); +.sp +.in +.hy +.ad +cc ... \-lpcp +.ft 1 +.SH DESCRIPTION +.de CW +.ie t \f(CW\\$1\fR\\$2 +.el \fI\\$1\fR\\$2 +.. +.B __pmControlLog +may be used to enable or disable the archive logging for particular performance +metrics, as identified by the +.I request +parameter; +see +.BR pmFetch (3) +for an explanation of the +.CW pmResult +structure. +.PP +The application must have previously issued a call to +.BR __pmConnectLogger (3) +to establish a control-port connection +to the +.BR pmlogger (1) +instance to whom the control request is to be directed, and +.I fd +(the result from +.BR __pmConnectLogger (3)) +identifies this connection. +.PP +Within +.IR request , +only the details of the performance metrics and their associated +instances will be used, i.e. +the values of the metrics, if any, will be ignored. +.I request +would typically be constructed as the result of an earlier call to +.BR pmFetch (3). +For metrics with a singular value (having an instance domain of +.BR PM_INDOM_NULL ) +the corresponding +.CW pmValueSet +should have the value one in the +.CW numval +field and +.B PM_IN_NULL +as the +.CW inst +field of the single +.CW pmValue +supplied. +If multiple explicit instances are to be logged, the +.CW numval +field of the +.CW pmValueSet +should contain the number of instances supplied and the +.CW inst +fields of the +.CW pmValue +structures should contain specific instance identifiers (which may not have the +reserved value +.BR PM_IN_NULL ). +.PP +If the +.CW numval +field within any of the +.CW pmValueSet +structures in +.I request +has a value of zero, it indicates that all available instances of the metric +should be used. Enumeration of the instance domain is deferred until the +logger fetches the metric prior to writing it to the log, rather than being +performed when the +.B __pmControlLog +request is received. This is useful for metrics with instance domains that +change over time. It is an error to specify +.CW numval +equal to zero if the corresponding metric has a singular value (no instance +domain). +.PP +There are several sorts of logging control available, namely mandatory or +advisory, as defined by the +.I control +argument, and on, off or maybe as defined by the +.I state +argument. These different types of control may be used to ensure that some +performance metrics can be guaranteed to always be in the log, while others may +be dynamically enabled or disabled as determined by the level and type of +system activity. +.PP +The actual action to be performed is defined by the combination of +.I control +and +.I state +as follows. +If +.I control +is +.B PM_LOG_MANDATORY +and +.I state +is +.BR PM_LOG_ON , +then logging is enabled. +If +.I control +is +.B PM_LOG_MANDATORY +and +.I state +is +.BR PM_LOG_OFF , +then logging is disabled. +If +.I control +is +.B PM_LOG_MANDATORY +and +.I state +is +.BR PM_LOG_MAYBE , +then subsequent advisory controls will be honored. If the logging state prior +to the request was mandatory (on or off), the state is changed to advisory off. +If the logging state was already advisory (either on or off), it remains +unchanged. If +.I control +is +.B PM_LOG_ADVISORY +and the last mandatory control for the metric was +.BR PM_LOG_MAYBE , +then logging is enabled or disabled as specified by the +.I state +argument, i.e. +.B PM_LOG_ON +or +.BR PM_LOG_OFF . +When the arguments +.I state +and +.I control +specify a request to change the logging behavior, the +argument +.I delta +defines the logging interval in milliseconds to be applied to all metrics and +instances identified in +.IR request . +.PP +The result argument +.I status +returns the current logging state for each of the nominated performance +metrics. There is a 1:1 correspondence between the elements of +.I request +and +.IR status. +For metrics in +.I request +that have +.CW pmValueSet s +with +.CW numval +equal to zero, the corresponding +.CW pmValueSet +in +.IR result +will contain a value for each available instance at the time of the call. Each +metric value in +.I status +will have the current logging state encoded in it. The detailed outcome of the +operation for each metric can be determined by comparing these values to that +requested via +.IR control , +.I state +and +.IR delta . +.PP +Macros defined in +.B <pcp/impl.h> +may be used to extract the state and logging interval from the returned metric +values. +.B PMLC_GET_ON +returns true if logging is on, or false if it is off; +.B PMLC_GET_MAND +returns true if logging is mandatory, or false if it is advisory; +.B PMLC_GET_INLOG +returns true if the metric has been logged at least once, or false otherwise; +.B PMLC_GET_AVAIL +returns true if the metric was available from its source the last time it was +supposed to be logged, or false if it was unavailable; and +.B PMLC_GET_DELTA +returns the current logging interval for the metric (in milliseconds). +.B PMLC_MAX_DELTA +defines the greatest +.I delta +that can be returned in an encoded metric value. +.PP +As a special case, when +.I control +is +.BR PM_LOG_ENQUIRE , +.I state +and +.I delta +are ignored, and +.I status +returns the current logging state of the nominated performance metrics (this +variant makes no changes to the logging state). +.PP +If the value of the logging interval is 0, either for +.I delta +in a request to change state to +.BR PM_LOG_ON , +or encoded in the value returned from +.BR PM_LOG_ENQUIRE , +then this corresponds to the special ``once only'' logging of metrics +that appear once in the archive log, and are never logged again. +.PP +.B __pmControlLog +returns zero on success. +.SH NOTE +This routine is not thread-safe as there is no serialization on the +use of the communication channel between the sending of the request +and receiving the reply. +It is assumed that the caller is single-threaded, +which is true for the only current user of this routine, namely +.BR pmlc (1). +.SH SEE ALSO +.BR pmlc (1), +.BR pmlogger (1), +.BR PMAPI (3), +.BR pmFetch (3) +and +.BR __pmConnectLogger (3). +.SH DIAGNOSTICS +.IP \f3PM_ERR_TOOSMALL\f1 +The number of metrics in +.I request +is less than one. +.IP \f3PM_ERR_VALUE\f1 +One or more of the +.CW pmValueSet s +in +.I request +had +.CW numval +(the number of instances) less than one. +.IP \f3EINVAL\f1 +An invalid combination of +.I control +and +.I state +was specified, or +.I delta +was negative. diff --git a/man/man3/pmconverttime.3 b/man/man3/pmconverttime.3 new file mode 100644 index 0000000..e882e6c --- /dev/null +++ b/man/man3/pmconverttime.3 @@ -0,0 +1,81 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000-2004 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMCONVERTTIME 3 "PCP" "Performance Co-Pilot" +.SH NAME +\f3__pmConvertTime\f1 \- convert \fBtm\fR structure to \fBtimeval\fR structure +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.br +#include <pcp/impl.h> +.sp +.ad l +.hy 0 +.in +8n +.ti -8n +int __pmConvertTime(struct tm *\fItmin\fP, struct timeval *\fIorigin\fP, struct\ timeval\ *\fIrslt\fP); +.sp +.in +.hy +.ad +cc ... \-lpcp +.ft 1 +.SH DESCRIPTION +.B __pmConvertTime +accepts a +.B tm +structure that has been filled in by +.BR __pmParseCtime (3) +and a reference time point +.BR origin , +and fills in the given +.B rslt +structure with the time the user meant when he specified a partial +.B ctime +or positive or negative time +.BR interval . +.PP +Typically, the argument +.B origin +is the start time for a PCP archive log, unless the user specified +a negative +.B interval +offset, in which case it is the end +time of the log. +.PP +.B __pmConvertTime +returns 0 if successful. +It returns \-1 and writes an error message to +.BR stderr , +if an error is detected. +.PP +Use +.BR pmNewZone (3), +.BR pmNewContextZone (3) +or +.BR pmUseZone (3) +to establish a new current timezone that will effect +.BR __pmConvertTime . +.SH SEE ALSO +.BR PMAPI (3), +.BR pmNewContextZone (3), +.BR pmNewZone (3), +.BR pmParseInterval (3), +.BR pmParseTimeWindow (3), +.BR pmUseZone (3), +.BR __pmParseCtime (3) +and +.BR __pmParseTime (3). diff --git a/man/man3/pmconvscale.3 b/man/man3/pmconvscale.3 new file mode 100644 index 0000000..bba7c67 --- /dev/null +++ b/man/man3/pmconvscale.3 @@ -0,0 +1,124 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000-2004 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMCONVSCALE 3 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmConvScale\f1 \- rescale a performance metric value +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.sp +.ad l +.hy 0 +.in +8n +.ti -8n +int pmConvScale(int \fItype\fP, const pmAtomValue *\fIival\fP, const\ pmUnits\ *\fIiunit\fP, pmAtomValue\ *\fIoval\fP, const\ pmUnits\ *\fIounit\fP); +.sp +.in +.hy +.ad +cc ... \-lpcp +.ft 1 +.SH DESCRIPTION +.de CW +.ie t \f(CW\\$1\f1\\$2 +.el \fI\\$1\f1\\$2 +.. +All performance metric values may be encoded in a +.CW pmAtomValue +union, defined as follows; +.PP +.ft CW +.nf +.in +0.5i +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 */ + pmValueBlock *vbp; /* pmValueBlock ptr */ +} pmAtomValue; +.in +.fi +.ft 1 +.PP +The encoding of a performance metric's dimensionality and scale uses +a +.CW pmUnits +structure; see +.BR pmLookupDesc (3). +.PP +Given a performance metric value pointed to by +.I ival +multiply it by a scale factor and return the value in +.IR oval . +The scaling takes place from the units defined by +.I iunit +into the units defined by +.IR ounit . +Both input and output units must have the same dimensionality. +.PP +The performance metric type for both input and output values is determined by +.IR type , +the value for which +is typically extracted from a +.CW pmDesc +structure, following a call to +.BR pmLookupDesc (3) +for a particular performance metric. +.PP +.B pmConvScale +is most useful when values returned via +.BR pmFetch (3), +(and possibly extracted using +.BR pmExtractValue (3)) +need to be normalized +into some canonical scale and units for the purposes of computation. +.PP +As a special case, if all components of the dimension are zero, then +this is treated as synonymous with a ``count'' dimension of one, +and so the ``count'' scale components determine the relative scaling. +This accommodates the case where performance metrics are +dimensionless, without special case handling on the part of the caller. +.SH SEE ALSO +.BR PMAPI (3), +.BR pmAtomStr (3), +.BR pmExtractValue (3), +.BR pmFetch (3), +.BR pmLookupDesc (3), +.BR pmPrintValue (3), +.BR pmTypeStr (3) +and +.BR pmUnitsStr (3). +.SH DIAGNOSTICS +.P +.B PM_ERR_CONV +.IP +.I iunit +and +.I ounit +have different dimensionality, or have inappropriate +.I type +.P +.B PM_ERR_UNIT +.IP +Inappropriate +.I iunit +or +.I ounit +parameter diff --git a/man/man3/pmctime.3 b/man/man3/pmctime.3 new file mode 100644 index 0000000..b5fd95b --- /dev/null +++ b/man/man3/pmctime.3 @@ -0,0 +1,83 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000-2004 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMCTIME 3 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmCtime\f1 \- format the date and time for a reporting timezone +.SH "C SYNOPSIS" +.ft 3 +#include <time.h> +.br +#include <pcp/pmapi.h> +.sp +char *pmCtime(const time_t *\fIclock\fP, char *\fIbuf\fP); +.sp +cc ... \-lpcp +.ft 1 +.SH DESCRIPTION +.B pmCtime +is very similar to +.BR ctime (3), +except the timezone used is the current ``reporting timezone'' (rather than the +default +.B TZ +environment variable scheme), and the result is returned into a +caller-declared buffer (rather than a private buffer). +.PP +Like +.BR ctime (3) +the time to be converted is passed via +.IR clock , +and +the result in +.I buf +is fixed width fields in the format: +.PP +.in +1i +Fri Sep 13 00:00:00 1986\en\e0 +.PP +The result buffer +.I buf +must be at least 26 bytes long, and no attempt is made to check this. +.B pmCtime +returns +.I buf +as the value of the function. +.PP +The default current reporting timezone is as defined by the +.B TZ +environment variable, so +.B pmCtime +and +.BR ctime (3) +will initially produce similar encoding of the date and time. +.PP +Use +.BR pmNewZone (3), +.BR pmNewContextZone (3) +or +.BR pmUseZone (3) +to establish a new current reporting timezone that will effect +.B pmCtime +but not +.BR ctime (3). +.SH SEE ALSO +.BR ctime (3), +.BR PMAPI (3), +.BR pmLocaltime (3), +.BR pmNewContextZone (3), +.BR pmNewZone (3) +and +.BR pmUseZone (3). diff --git a/man/man3/pmda.3 b/man/man3/pmda.3 new file mode 100644 index 0000000..20194f6 --- /dev/null +++ b/man/man3/pmda.3 @@ -0,0 +1,743 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000-2004 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.\" add in the -me strings for super and subscripts +.ie n \{\ +. ds [ \u\x'-0.25v' +. ds ] \d +. ds { \d\x'0.25v' +. ds } \u +.\} +.el \{\ +. ds [ \v'-0.4m'\x'-0.2m'\s-3 +. ds ] \s0\v'0.4m' +. ds { \v'0.4m'\x'0.2m'\s-3 +. ds } \s0\v'-0.4m' +.\} +.TH PMDA 3 "PCP" "Performance Co-Pilot" +.SH NAME +\f3PMDA\f1 \- introduction to the Performance Metrics Domain Agent support library +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.br +#include <pcp/impl.h> +.br +#include <pcp/pmda.h> +.sp +cc ... \-lpcp_pmda \-lpcp +.ft 1 +.SH DESCRIPTION +.de CW +.ie t \f(CW\\$1\f1\\$2 +.el \fI\\$1\f1\\$2 +.. +To assist in the development of Performance Metric Domain Agents +.RB ( PMDA s) +for the Performance Co-Pilot (PCP), +a procedural interface is provided that extends the Performance Metrics +Application Programming Interface ( +.BR PMAPI (3)) +library. These procedures are designed to enable a programmer to quickly +build a +.B PMDA +which can then be tested and refined. However, this also +implies that a +.B PMDA +has a particular structure which may not be suitable for +all applications. +.PP +Once you are familiar with the PCP and +.B PMDA +frameworks, you can quickly implement a new +.B PMDA +with only a few data structures and functions. This is covered in far greater +detail in the +.IR "Performance Co-Pilot Programmer's Guide" . +.PP +A +.B PMDA +is responsible for a set of performance metrics, in the sense that it must +respond to requests from +.BR pmcd(1) +for information about performance metrics, instance domains, and instantiated +values. The +.BR pmcd (1) +process generates requests on behalf of performance tools that make requests +using +.BR PMAPI (3) +routines. +.PP +This man page contains sections of the +.B simple PMDA +which is located at +.IR $PCP_PMDAS_DIR/simple . +.SH COMMUNICATING WITH PMCD +Two approaches may be used for connecting a +.B PMDA +to a +.BR pmcd (1) +process. A Dynamic Shared Object (DSO) can be attached by +.BR pmcd (1) +using +.BR dlopen (3) +when the +.BR pmcd (1) +process is started. A procedural interface referenced through a shared data +structure is used to handle requests from +.BR pmcd (1) +to the +.BR PMDA . +.PP +The preferred approach is for a separate process (daemon) to communicate with +.BR pmcd (1) +using the Performance Data Units (PDU) Inter-Process Communication (IPC) +protocol. +.PP +All +.BR PMDA s +are launched and controlled by the +.BR pmcd (1) +process on the local host. The requests from the clients are received by +.BR pmcd (1) +and forwarded to the appropriate +.BR PMDA s. +Responses, when required, are returned through +.BR pmcd (1) +to the clients. The requests (PDUs) that may be sent to a +.B PMDA +from +.BR pmcd (1) +are +.BR PDU_FETCH , +.BR PDU_PROFILE , +.BR PDU_INSTANCE_REQ , +.BR PDU_DESC_REQ , +.BR PDU_TEXT_REQ +and +.BR PDU_RESULT . +.SH DEFAULT CALLBACKS FOR HANDLING PDUs +To allow a consistent framework, +.BR pmdaMain (3) +can be used by a daemon +.B PMDA +to handle the communication protocol using the same callbacks as a DSO +.BR PMDA . +The structure +.B pmdaInterface +is used to convey the common procedural interface and state information that is +used by +.BR pmcd (1) +and a +.BR PMDA . +This state information includes tables describing the supported metrics and +instance domains. +.PP +As most of the +procedural interface is identical for all +.BR PMDA s, +they are provided as part of +this support library +.RB ( pmdaProfile (3), +.BR pmdaFetch (3), +.BR pmdaInstance (3), +.BR pmdaDesc (3), +.BR pmdaText (3) +and +.BR pmdaStore (3)). +However, these routines require access to the +.B pmdaInterface +state information so it must be correctly initialized using +.BR pmdaConnect (3), +.BR pmdaDaemon (3), +.BR pmdaOpenLog (3), +.BR pmdaDSO (3), +.BR pmdaGetOpt (3) +and +.BR pmdaInit (3). +.SH INSTANCES AND INSTANCE DOMAINS +Three structures are declared in +.I /usr/include/pcp/pmda.h +which provide a framework for declaring the metrics and instances supported by +the +.BR PMDA . +.PP +Every instance requires a unique integer identifier and a unique name, as defined by +the structure +.BR pmdaInstid : +.PP +.nf +.ft CW +.in +0.5i +/* + * Instance description: index and name + */ + +typedef struct { + int i_inst; /* internal instance identifier */ + char *i_name; /* external instance identifier */ +} pmdaInstid; +.in +.fi +.PP +An instance domain requires its own unique identification +.RB ( pmInDom ), +the number of instances the domain represents, and a pointer to an array of +instance descriptions. This is defined in the structure +.BR pmdaIndom : +.PP +.nf +.ft CW +.in +0.5i +/* + * Instance domain description: unique instance id, + * number of instances in this domain, and the list of + * instances (not null terminated). + */ + +typedef struct { + pmInDom it_indom; /* indom, filled in */ + int it_numinst; /* number of instances */ + pmdaInstid *it_set; /* instance identifiers */ +} pmdaIndom; +.in +.fi +.ft 1 +.PP +The +.B simple PMDA +has one instance domain for +.IR simple . color +with three instances +.RI ( red , +.I green +and +.IR blue ), +and a second instance domain for +.IR simple . now +with instances which can be specified at run-time. +These instance domains are defined as: +.PP +.nf +.ft CW +.in +0.5i +static pmdaInstid _color[] = { + { 0, "red" }, { 1, "green" }, { 2, "blue" } +}; +static pmdaInstid *_timenow = NULL; + +static pmdaIndom indomtab[] = { +#define COLOR_INDOM 0 + { COLOR_INDOM, 3, _color }, +#define NOW_INDOM 1 + { NOW_INDOM, 0, NULL }, +}; +.in +.fi +.PP +The preprocessor macros +.B COLOR_INDOM +and +.B NOW_INDOM +are used in the metric description table to identify the instance domains of +individual metrics. These correspond to the +.I serial +value in the instance domain +.B pmInDom +structure (the +.I domain +field is set by +.BR pmdaInit (3) +at run-time). The serial value must be unique for each instance domain +within the +.BR PMDA . +.PP +The indom table shown above which is usually passed to +.BR pmdaInit (3) +does not need to be created +if one wants to write one's own Fetch and Instance functions. +See +.BR pmdaInit (3) +for more details. +.SH NAMESPACE +Every +.B PMDA +has its own unique +.B namespace +using the format defined in +.BR pmns (5). +In summary, the namespace matches the names of the metrics to the unique +identifier. The +.B simple PMDA +defines five metrics: +.IR simple . numfetch , +.IR simple . color , +.IR simple . time . user, +.IR simple . time . sys +and +.IR simple . now . +The namespace for these metrics is defined in +.I $PCP_PMDAS_DIR/simple/pmns +and is installed as: +.PP +.nf +.ft CW +.in +0.5in +simple { + numfetch 253:0:0 + color 253:0:1 + time + now 253:2:4 +} + +simple.time { + user 253:1:2 + sys 253:1:3 +} +.in +.fi +.PP +The domain number of +.I 253 +is obtained from +.IR $PCP_VAR_DIR/pmns/stdpmid . +New +.BR PMDA s +should specify a unique domain number in this file, and obtain the +number during installation. This allows the domain number to change by +modifying only the file +.IR $PCP_VAR_DIR/pmns/stdpmid . +.PP +The +.I simple.time +and +.I simple.now +metrics are defined in separate clusters to the other metrics which allows a +.B PMDA +to support more than 1024 metrics, as well as grouping similar metrics +together. Therefore, the item numbers for a new cluster may be identical to +the item numbers in other clusters. The +.B simple PMDA +continues to increment the item numbers to permit direct mapping (see +.BR pmdaInit (3)). +.PP +The namespace file should be installed and removed with the agent using +.BR pmnsadd (1) +and +.BR pmnsdel (1). +See the later sections on INSTALLATION and REMOVAL. +.PP +A simple ASCII namespace can be constructed by creating a file similar to +.IR $PCP_PMDAS_DIR/simple/root : +.PP +.nf +.ft CW +.in +0.5i +/* + * fake "root" for validating the local PMNS subtree + */ + +#include "$PCP_VAR_DIR/pmns/stdpmid" + +root { simple } + +#include "pmns" + +.in +.fi +.PP +and can be referred to with the +.B \-n +option in most PCP tools. +.SH METRIC DESCRIPTIONS +Each metric requires a description +.RB ( pmDesc ), +which contains its PMID, data type specification, instance domain, semantics +and units (see +.BR pmLookupDesc (3)). +A handle is also provided for application specific information in the +.B pmdaMetric +structure: +.PP +.nf +.ft CW +.in +0.5i +/* + * Metric description: handle for extending description, + * and the description. + */ + +typedef struct { + void* m_user; /* for users external use */ + pmDesc m_desc; /* metric description */ +} pmdaMetric; +.in +.fi +.PP +The +.B simple PMDA +defines the metrics as: +.PP +.nf +.ft CW +.in +0.5i +static pmdaMetric metrictab[] = { +/* numfetch */ + { (void *)0, + { PMDA_PMID(0,0), PM_TYPE_U32, PM_INDOM_NULL, PM_SEM_INSTANT, + { 0,0,0,0,0,0} }, }, +/* color */ + { (void *)0, + { PMDA_PMID(0,1), PM_TYPE_32, COLOR_INDOM, PM_SEM_INSTANT, + { 0,0,0,0,0,0} }, }, +/* time.user */ + { (void*)0, + { PMDA_PMID(1,2), PM_TYPE_DOUBLE, PM_INDOM_NULL, PM_SEM_COUNTER, + { 0, 1, 0, 0, PM_TIME_SEC, 0 } }, }, +/* time.sys */ + { (void*)0, + { PMDA_PMID(1,3), PM_TYPE_DOUBLE, PM_INDOM_NULL, PM_SEM_COUNTER, + { 0, 1, 0, 0, PM_TIME_SEC, 0 } }, }, +/* now */ + { NULL, + { PMDA_PMID(2,4), PM_TYPE_U32, NOW_INDOM, PM_SEM_INSTANT, + { 0,0,0,0,0,0 } }, }, +}; +.in +.fi +.PP +The macro +.B PMDA_PMID +(defined in +.IR /usr/include/pcp/pmda.h ) +is used to specify each metric's +.I cluster +and +.I unit +number in the +.B __pmID_int +structure defined in +.IR /usr/include/pcp/impl.h . +As with instance domains, the +.I domain +field is set by +.BR pmdaInit (3) +at run-time, however, the default domain is assumed to be defined by the +.B PMDA +in the macro +.BR MYDOMAIN . +.PP +The metric table shown above which is usually passed to +.BR pmdaInit (3) +does not need to be created +if one wants to write one's own Fetch and Descriptor functions. +See +.BR pmdaInit (3) +for more details. +.SH DSO PMDA +A +.B PMDA +that is run as a DSO is opened by +.BR pmcd (1) +with +.BR dlopen (3). +.B pmcd +will call the +.BR PMDA "'s" +initialization function that is specified in +.IR $PCP_PMCDCONF_PATH. +This function is passed a pointer to a +.B pmdaInterface +structure which must be completed. Any callbacks which are +.I not +the default +.B PMDA +support library callbacks must be specified in the +.B pmdaInterface +structure. +.PP +The +.B simple PMDA +uses its own store and fetch callback. +.BR simple_fetch () +calls +.BR pmdaFetch (3) +which requires a callback to be set with +.BR pmdaSetFetchCallBack (3) +as can be seen in +.IR $PCP_PMDAS_DIR/simple/simple.c . +.PP +The flag +.B _isDSO +is used to determine if the +.B PMDA +is a daemon or a DSO so that the correct initialization +routine, +.BR pmdaDaemon (3) +or +.BR pmdaDSO (3), +is called. +.SH DAEMON PMDA +A +.B PMDA +that is run as a daemon is forked and executed by +.BR pmcd (1). +Therefore, unlike a DSO +.BR PMDA , +the starting point for a daemon +.B PMDA +is +.BR main (). +The agent should parse the command line arguments, create +a log file and initialize some data structures that +.B pmcd +would initialize for a DSO agent. +.PP +The +.B pmdaInterface +structure must be completely defined by the daemon +.BR PMDA . +The function +.BR pmdaDaemon (3) +can be called at the start of +.BR main () +to set most of these fields. Command line parsing can be simplified by using +.BR pmdaGetOpt (3), +which is similar to +.BR getopt (2), +but extracts a common set of options into the +.B pmdaInterface +structure. +.I stderr +can be mapped to a log file using +.BR pmdaOpenLog (3) +to simplify debugging and error messages. The connection to +.B pmcd +can be made with +.BR pmdaConnect (3) +and the loop which handles the incoming PDUs, +.BR pmdaMain (3), +should be the last function called. This can be seen in +.IR $PCP_PMDAS_DIR/simple/simple.c . +.PP +The +.BR simple_init () +routine is common to an agent that can be run as both a Daemon and DSO +.BR PMDA . +.SH HELP TEXT +Each +.B PMDA +must be able to provide +.B pmcd +with the help text for each metric. Most +.BR PMDA s +use specially created files with indexes to support +efficient retrieval of the help text. +Tools are provided with PCP to +create the help text files of appropriate format. See +.BR newhelp (1). +.SH INSTALLATION AND REMOVAL +A series of shell procedures are defined in +.I $PCP_SHARE_DIR/lib/pmdaproc.sh +which greatly simplify the installation and removal of a +.BR PMDA . +The +.I Install +scripts for most +.BR PMDAs +should only need to specify the name of the +.B PMDA +in +.BR iam , +call +.B _setup +which check licenses and whether the +.B PMDA +has been previously installed, +specify the communication protocols, +and finally call +.BR _install . +The +.I Remove +scripts are even simpler as the communication protocols are not required. +Further information is contained in the +.I $PCP_SHARE_DIR/lib/pmdaproc.sh +file. +.SH DIAGNOSTICS +Any +.B PMDA +which uses this library can set +.BR PMAPI (3) +debug control variable +.B pmDebug +(with \-D on the command line) to +.B DBG_TRACE_LIBPMDA +to enable the display of debugging information which may be useful during +development +(see +.BR pmdbg (1)). +.PP +The +.I status +field of the +.B pmdaInterface +structure should be zero after +.BR pmdaDaemon , +.BR pmdaDSO , +.BR pmdaGetOpt , +.BR pmdaConnect +and +.B pmdaInit +are called. A value less than zero indicates that initialization has failed. +.PP +Some error messages that are common to most functions in this library are: +.TP 15 +.BI "PMDA interface version " interface " not supported" +Most of the functions require that the +.I comm.version +field of the +.B pmdaInterface +structure be set to +.B PMDA_INTERFACE_2 +or later. +.B PMDA_INTERFACE_2 +or +.B PMDA_INTERFACE_3 +implies that the +.I version.two +fields are correctly initialized, +while +.B PMDA_INTERFACE_4 +implies that the +.I version.four +fields are correctly initialized +(see +.BR pmdaDaemon (3) +and +.BR pmdaDSO (3)). +.SH CAVEAT +Failing to complete any of the data structures or calling any of the library +routines out of order may cause unexpected behavior in the +.BR PMDA . +.PP +Due to changes to the +.BR PMAPI (3) +and +.BR PMDA (3) +API in the PCP 2.0 release, as described in the product release notes, +.BR PMDA s +built using PCP 2.0 must specify +.B PMDA_INTERFACE_2 +or later and link with +.I libpcp_pmda.so.2 +and +.IR libpcp.so.2 . +Pre-existing Daemon PMDAs specifying +.B PMDA_PROTOCOL_1 +will continue to function using the backwards compatible +.I libpcp_pmda.so.1 +and +.I libpcp.so.1 +libraries and may be recompiled using the headers installed in +.I "/usr/include/pcp1.x/" +without any modification. These backwards compatible headers and libraries +are contained in the +.I pcp.sw.compat +subsystem. +.SH FILES +.TP 10 +.I /usr/include/pcp/pmda.h +Header file for the +.B PMDA +support library. +.TP +.I /usr/lib/libpcp_pmda.so +Dynamic library containing +.B PMDA +support library routines. +.TP +.I $PCP_PMDAS_DIR/trivial +The source of the +.BR "trivial PMDA" . +.TP +.I $PCP_PMDAS_DIR/simple +The source of the +.BR "simple PMDA" . +.TP +.I $PCP_PMDAS_DIR/txmon +The source of the +.BR "txmon PMDA" . +.TP +.I $PCP_PMCDCONF_PATH +Configuration file for +.BR pmcd (1). +.TP +.I $PCP_VAR_DIR/pmns +Location of namespace descriptions for every +.BR PMDA . +.TP +.I $PCP_VAR_DIR/pmns/stdpmid +The unique domain identifiers for each +.BR PMDA . +.TP +.I $PCP_SHARE_DIR/lib/pmdaproc.sh +Shell procedures for installing and removing a +.BR PMDA . +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.I /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). +Values for these variables may be obtained programmatically +using the +.IR pmGetConfig (3) +function. +.SH SEE ALSO +.BR dbpmda (1), +.BR newhelp (1), +.BR pmcd (1), +.BR pmnsadd (1), +.BR pmnsdel (1), +.BR PMAPI (3), +.BR pmdaConnect (3), +.BR pmdaDaemon (3), +.BR pmdaDesc (3), +.BR pmdaDSO (3), +.BR pmdaFetch (3), +.BR pmdaGetOpt (3), +.BR pmdaInit (3), +.BR pmdaInstance (3), +.BR pmdaMain (3), +.BR pmdaOpenLog (3), +.BR pmdaProfile (3), +.BR pmdaStore (3), +.BR pmdaText (3), +.BR pmLookupDesc (3) +and +.BR pmns (5). +.PP +For a complete description of the +.I pcp_pmda +library and the PMDA development process, refer to the Insight book +.IR "Performance Co-Pilot Programmer's Guide" . diff --git a/man/man3/pmdaattribute.3 b/man/man3/pmdaattribute.3 new file mode 100644 index 0000000..69d1be6 --- /dev/null +++ b/man/man3/pmdaattribute.3 @@ -0,0 +1,104 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2013 Red Hat. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMDAATTRIBUTE 3 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmdaAttribute\f1 \- informs a PMDA about client connection attributes +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.br +#include <pcp/impl.h> +.br +#include <pcp/pmda.h> +.sp +int pmdaAttribute(int \fIcontext\fP, int \fIkey\fP, char *\fIvalue\fP, int \fIlength\fP, pmdaExt *\fIpmda\fP); +.sp +cc ... \-lpcp_pmda \-lpcp +.ft 1 +.SH DESCRIPTION +As part of the Performance Metrics Domain Agent (PMDA) API (see +.BR PMDA (3)), +.B pmdaAttribute +is the generic callback for responding to client connection attributes. +These attributes include client credential information, such as user ID +and group ID. +.PP +A PMDA that supports connection attributes will provide a private +.B pmdaAttribute +callback +by assignment to +.I version.six.attribute +of the +.I pmdaInterface +structure, and implement custom logic for any of the attribute +.IR key \-\c +.I value +pairs of interest to it. +.PP +All attributes are associated with a specific client context, and these +can be uniquely identified using the +.I ctx +first argument. +The PMDA should track client connections, and disconnections using the +.BR pmdaSetEndContextCallBack (3) +interface, as a result. +The +.BR pmdaGetContext (3) +interface may be particularly helpful also. +.PP +All attributes are passed as +.IR key \-\c +.I value +pairs and the +.I value +is always passed as a null-terminated string of given +.IR length . +This includes numeric attributes like the user ID. +.PP +The most commonly used attributes would be PCP_ATTR_USERID and PCP_ATTR_GROUPID +but others may also be optionally passed (such as PCP_ATTR_USERNAME) if they are +available. +Some attributes will be consumed by +.B pmcd +and never through passed to PMDAs, such as PCP_ATTR_PASSWORD. +A complete list of all possible attributes can be found in the headers listed +above, all are prefixed by PCP_ATTR. +.SH DIAGNOSTICS +.B pmdaAttribute +should return either zero on success, or a negative return code +to indicate an error in handling the attribute. +This return code cannot be used to indicate a client should be +disallowed access \- such functionality must be performed by the agent in +response to callbacks for the client in question (using PM_ERR_PERMISSION +for those specific callbacks, for that specific client. +In other words, errors will be be passed to PMCD but there is no guarantee +made that the error will be return to the client and result in termination +of the client, for example. +.SH CAVEAT +The PMDA must be using +.B PMDA_PROTOCOL_6 +or later, as specified in the call to +.BR pmdaDSO (3) +or +.BR pmdaDaemon (3). +.SH SEE ALSO +.BR PMAPI (3), +.BR PMDA (3), +.BR pmdaDaemon (3), +.BR pmdaDSO (3), +.BR pmdaMain (3) +and +.BR pmdaGetContext (3). diff --git a/man/man3/pmdacache.3 b/man/man3/pmdacache.3 new file mode 100644 index 0000000..d0b6726 --- /dev/null +++ b/man/man3/pmdacache.3 @@ -0,0 +1,704 @@ +'\"! tbl | mmdoc +'\"macro stdmacro +.\" +.\" Copyright (c) 2013 Red Hat. +.\" Copyright (c) 2000-2004 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMDACACHE 3 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmdaCacheStore\f1, +\f3pmdaCacheStoreKey\f1, +\f3pmdaCacheLookup\f1, +\f3pmdaCacheLookupName\f1, +\f3pmdaCacheLookupKey\f1, +\f3pmdaCacheOp\f1, +\f3pmdaCachePurge\f1 \- manage a cache of instance domain information for a PMDA +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.br +#include <pcp/pmda.h> +.sp +.ad l +.hy 0 +.in +8n +.ti -8n +int pmdaCacheStore(pmInDom \fIindom\fP, int \fIflags\fP, const\ char\ *\fIname\fP, void\ *\fIprivate\fP); +.br +.ti -8n +int pmdaCacheStoreKey(pmInDom \fIindom\fP, int \fIflags\fP, const\ char\ *\fIname\fP, int\ \fIkeylen\fP, const void\ *\fIkey\fP, void\ *\fIprivate\fP); +.br +.ti -8n +int pmdaCacheLookup(pmInDom \fIindom\fP, int \fIinst\fP, char **\fIname\fP, void\ **\fIprivate\fP); +.br +.ti -8n +int pmdaCacheLookupName(pmInDom \fIindom\fP, const char *\fIname\fP, int\ *\fIinst\fP, void\ **\fIprivate\fP); +.br +.ti -8n +int pmdaCacheLookupKey(pmInDom \fIindom\fP, const char *\fIname\fP, int\ \fIkeylen\fP, const void\ *\fIkey\fP, char **\fIoname\fP, int\ *\fIinst\fP, void\ **\fIprivate\fP); +.br +.ti -8n +int pmdaCacheOp(pmInDom \fIindom\fP, int \fIop\fP); +.br +.ti -8n +int pmdaCachePurge(pmInDom \fIindom\fP, time_t \fIrecent\fP); +.sp +.in +.hy +.ad +cc ... \-lpcp_pmda \-lpcp +.ft 1 +.de EX +.in +2n +.ie t .ft C +.el .ft B +.ie t .sp .5v +.el .sp +.ta \\w' 'u*8 +.nf +.. +.de EE +.fi +.ie t .sp .5v +.el .sp +.ft R +.in +.. +.SH DESCRIPTION +The +.B pmdaCache +family of routines provide services to support the maintenance of +complex instance domains for Performance Co-Pilot PMDAs. +There is potentially one cache of information for each instance +domain, and for each instance the cache maintains: +.PD 0 +.IP \- 2m +external instance name (supplied by the PMDA) +.IP \- 2m +internal instance identifier (assigned by +.B pmdaCacheStore +or calculated from a ``hint'' by +.BR pmdaCacheStoreKey ) +.IP \- 2m +state, where +.B active +instances are visible and part of the current +instance domain, and +.B inactive +instances are hidden, but not forgotten; +.B pmdaCacheStore +or +.B pmdaCacheStoreKey +may be used to change the state of an instance +.IP \- 2m +an optional opaque pointer to data that is associated with the instance, +but maintained by the PMDA +.IP \- 2m +an optional opaque key that is used as a ``hint'' to +.B pmdaCacheStoreKey +when guessing the initial internal instance identifier +.IP \- 2m +the last time the cache was saved and the instance had been marked as +.B active +at some point since the previous cache load or save operation +.PD +.PP +The semantics of a PCP instance domain require a number of rules to +be followed, namely: +.PD 0 +.IP 1. 3n +Each internal instance identifier must be unique and in the range +0 to 2^31\0\-\01. +This rule is enforced by the +.B pmdaCache +family of routines. +.IP 2. 3n +The external instance name must be unique. When the instance name +contains a space, it is further constrained such that the name to +the left of the first space (the short name) must also be unique. +Refer to the INSTANCE NAME MATCHING section below. +The PMDA must honor this rule, the +.B pmdaCache +family of routines will detect attempts to violate this rule. +.IP 3. 3n +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, e.g. ``/dev/hda'' is always the name of the same disk +on a particular system. +This rule is perhaps the responsibility of the PMDA, but is often +a characteristic of the environment in which the PMDA runs. +.IP 4. 3n +It is preferable, although not mandatory, for the association between +and external instance name and an internal instance identifier to +be persistent. +This rule is supported by the +.B pmdaCache +family of routines. +.IP 5. 3n +When opaque keys are used, the values of the keys must be unique across all +instances within an instance domain. +This rule is enforced by the +.B pmdaCache +family of routines. +.PD +.PP +The visible interface to the cache is oriented towards the PMDA +developer who is most concerned about the names of instances, while +the details of how the rest of the PCP infrastructure +expects the internal instance identifiers +to be managed is not relevant. +.PP +Instances are updated in the cache for instance domain +.I indom +by calling +.B pmdaCacheStore +or +.B pmdaCacheStoreKey +with the external name of the instance passed via +.I name. +The opaque pointer +.I private +may be used to associate additional data with the entry in the cache; +if no such data is required, +.I private +should be NULL. +Any manipulation of the additional data (including allocation or +freeing) is the responsibility of the PMDA caller, as the cache simply +maintains the pointer to the data +(passed via +.IR private ). +.PP +For cases where the PMDA developer wishes to influence the allocation +of internal instance identifiers, e.g. for instance domains with more +than one natural dimension, or where there is a desire to allocate the same +instance identifier each time the PMDA is started, even on different +hosts, +.B pmdaCacheStoreKey +may be used. +In this case, an initial ``hint'' for the instance identifier is provided +as an opqaue key via +the first +.I keylen +bytes in +.I key +(which could be any sort of data, including binary values) +else if +.I keylen +is less than 1 or +.I key +is +.B NULL +then +.I name +is used as the ``hint''. +The ``hint'' is hashed to produce an initial instance identifier in the range +0 to 2^31\0-\01. If this instance identifier is already allocated, then the +value is rehashed. This procedure is repeated until an unallocated +instance identifier is found, or +.B pmdaCacheStoreKey +gives up and returns +.BR PM_ERR_GENERIC . +For each instance domain, the ``hint'' must be unique across all +instances, else +.B pmdaCacheStoreKey +returns +.BR PM_ERR_INST . +.PP +The +.I flags +argument controls how the instance should be processed in the cache +as follows: +.TP +PMDA_CACHE_ADD +Insert the entry into the cache if it is not already there and mark +it +.BR active . +If the entry is already in the cache mark it +.BR active . +.TP +PMDA_CACHE_HIDE +Mark the entry in the cache as +.BR inactive , +but remember the +details of the association between the +external instance name and the internal instance identifier. +Entries that are +.B inactive +will be hidden from cache traversal via PMDA_CACHE_WALK_NEXT +operations, but remain visible to +.BR pmdaCacheLookup , +.B pmdaCacheLookupName +and +.B pmdaCacheLookupKey +requests. +.TP +PMDA_CACHE_CULL +Remove the entry from the cache. +.PP +On success +.B pmdaCacheStore +or +.B pmdaCacheStoreKey +will return the internal instance identifier of the associated cache +entry. +Valid instance identifiers are guaranteed to be unique and non-negative. +Failure will be indicated by a negative value (suitable for decoding +with +.BR pmErrStr (3)) +and most likely PM_ERR_INST to indicate the requested instance is not +in the cache, or \-EINVAL to indicate a potential violation of the +short name uniqueness property +(see the INSTANCE NAME MATCHING section below). +.PP +.B pmdaCacheLookup +is used to search the +entries in the cache based on the internal +instance identifier +.IR inst . +.PP +On success the return value will be PMDA_CACHE_ACTIVE or PMDA_CACHE_INACTIVE +(depending on the +.B active +or +.B inactive +state of the cache entry), +.I name +(if not NULL) and +.I private +(if not NULL) +will be set to the external instance name and the associate additional data +area as provided when the instance was last activated via +.B pmdaCacheStore +or +.BR pmdaCacheStoreKey . +.PP +.B pmdaCacheLookup +failure is indicated by a negative return value +suitable for decoding with +.BR pmErrStr (3). +.PP +The +.B pmdaCacheLookup +interface is required by the PMDA's fetch callback +that is registered via +.BR pmdaSetFetchCallback (3). +Here the internal instance identifier is passed to the fetch callback +to identifier for which instance a value is required. +Typical usage is shown in the code fragment below. +.EX +static int +foo_callback(pmdaMetric *mdesc, unsigned int inst, pmAtomValue *atom) +{ + mydata *mdp; + char *name; + int sts; + + sts = pmdaCacheLookup(mdesc->m_desc.indom, inst, &name, (void **)&mdp); + /* + * expect sts == PMDA_CACHE_ACTIVE except for cataclysmic events + * use mdp as required, name may be useful for diagnostics + */ + ... +.EE +.PP +.B pmdaCacheLookupName +is used to search the +entries in the cache based on the external +instance name +.IR name . +.PP +On success the return value will be PMDA_CACHE_ACTIVE or PMDA_CACHE_INACTIVE +(depending on the +.B active +or +.B inactive +state of the cache entry), +.I inst +(if not NULL) and +.I private +(if not NULL) +will be set to the internal instance identifier and the associate additional data +area as provided when the instance was last activated via +.B pmdaCacheStore +or +.BR pmdaCacheStoreKey . +.PP +.B pmdaCacheLookupName +failure is indicated by a negative return value +suitable for decoding with +.BR pmErrStr (3). +.PP +The +.B pmdaCacheLookupName +interface is useful for PMDAs wishing to update an instance domain based +on the external instance names. +.PP +.B pmdaCacheLookupKey +is used to search the entries in the cache +based on an opaque key (or ``hint'') previously used in a call to +.BR pmdaCacheStoreKey . +The ``hint'' is provided via the first +.I keylen +bytes in +.IR key . +For symmetry with +.BR pmdaCacheStoreKey , +if +.I keylen +is less than 1 or +.I key +is +.B NULL +then +.I name +is used as the ``hint'' (although the results will be the same as +calling +.B pmdaCacheLookupName +in this case). +.PP +On success the return value will be PMDA_CACHE_ACTIVE or PMDA_CACHE_INACTIVE +(depending on the +.B active +or +.B inactive +state of the cache entry), +.I oname +(if not NULL), +.I inst +(if not NULL) and +.I private +(if not NULL) +will be set to the external instance name, the internal instance +identifier and the associate additional data +area as provided when the instance was last activated via +.B pmdaCacheStore +or +.BR pmdaCacheStoreKey . +.PP +.B pmdaCacheLookupKey +failure is indicated by a negative return value +suitable for decoding with +.BR pmErrStr (3). +.PP +To avoid a persistent cache growing without bound, +.B pmdaCachePurge +can be used to cull all entries that have +.I not +been +.B active +in the last +.I recent +seconds. +For performance reasons, the time accounting is imprecise and the entries +are timestamped +at the time of the next cache save operation +.I after +the entry has been added or marked +.B active +(refer to PMDA_CACHE_SAVE and PMDA_CACHE_SYNC below). +On success +.B pmdaCachePurge +returns the number of culled entries, else in the case of an error +the return value is negative (and suitable for decoding with +.BR pmErrStr (3)). +.PP +.B pmdaCacheOp +may be used to perform additional operations on the cache as follows: +.TP +PMDA_CACHE_LOAD +The cache can optionally be maintained as a persistent external file, +so that the mapping of instance names to instance identifiers is persistent +across executions of a PMDA. +This operation loads the cache from the external file, and then +all new cache entries are marked +.BR inactive , +and the additional +data pointer is set to NULL. +Entries loaded from the external file are checked against the current +cache contents and if the instance name and instance identifiers match +then the state in the cache (\c +.B active +or +.BR inactive ) +is not changed. Should a mismatch be found (same instance name and +different instance identifier, or same instance identifier and different +instance name, or some but not all of the instance identifier, +the instance name and the ``hint'' match) +then the entry from the external file is ignored +and a warning is issued on +.IR stderr . +Typically a PMDA would only +perform this operation once per execution. +.TP +PMDA_CACHE_SAVE +If any instance has been added to, or deleted from, the instance +domain since the last PMDA_CACHE_LOAD, PMDA_CACHE_SAVE or PMDA_CACHE_SYNC +operation, the +.I entire +cache is written to the external file as a bulk operation. +This operation is provided for PMDAs that are +.I not +interested +in using +.B pmdaCachePurge +and simply want the external file to reflect the set of known instances +without accurate details of when they were last marked +.BR active . +.RS +.PP +Returns the number of instances saved to the external file, else 0 +if the external file was already up to date. +.RE +.TP +PMDA_CACHE_STRINGS +Annotates this cache as being a special-purpose cache used for string +de-duplication in PMDAs exporting large numbers of string valued metrics. +This can be used to reduce the memory footprint of the PMDA (duplicate +strings hash to the same bucket, and are stored in memory once only). +Key comparisons are not terminated at the first space but rather the +entire string is used for matching. +These are specialised caches not useful for general purpose instance +domain handling. +.TP +PMDA_CACHE_SYNC +Within an instance domain, +if any instance has been added to, or deleted from, or marked +.B active +since the last PMDA_CACHE_LOAD, PMDA_CACHE_SAVE or PMDA_CACHE_SYNC +operation, the +.I entire +cache is written to the external file as a bulk operation. +This operation is similar to PMDA_CACHE_SAVE, but will save the +instance domain more frequently so the timestamps more +accurately match the semantics expected by +.BR pmdaCachePurge . +.RS +.PP +Returns the number of instances saved to the external file, else 0 +if the external file was already synchronized. +.RE +.TP +PMDA_CACHE_CHECK +Returns 1 if a cache exists for the specified instance domain, +else 0. +.TP +PMDA_CACHE_REUSE +When a new instance is added to the cache, +the default strategy is to assign instance identifiers in a monotonic +increasing +manner. Once the maximum possible instance identifier value has been +assigned, the strategy changes to one where starting from 0, +the next available unused instance identifier will be used. +Calling +.B pmdaCacheOp +with PMDA_CACHE_REUSE forces an irreversible change to a second +(reuse) strategy where the next unallocated instance identifier +will be used. This may be useful in cases where there is a +desire to restrict the allocated instance identifiers to smaller +values. The prevailing strategy will be saved and restored across +PMDA_CACHE_SAVE and PMDA_CACHE_LOAD operations. +If +.B pmdaCacheStoreKey +is ever used, the associated instance domain will be changed to +PMDA_CACHE_REUSE mode. +.TP +PMDA_CACHE_REORG +Reorganize the cache to allow faster retrieval of +.B active +entries, and the cost of slower retrieval for +.B inactive +entries, and reclaim any culled entries. The cache may be internally +re-organized as entries are added, so this operation is not required +for most PMDAs. +.TP +PMDA_CACHE_WALK_REWIND +Prepares for a traversal of the cache in ascending instance identifier +sequence. +.TP +PMDA_CACHE_WALK_NEXT +Fetch the next +.B active +instance identifier from the cache. Requires a prior +call using PMDA_CACHE_WALK_REWIND and will return \-1 when all instances +have been processed. +.RS +.PP +Only one cache walk can be active at any given time, nesting calls +to PMDA_CACHE_WALK and PMDA_CACHE_REWIND will interfere with each +other. +.RE +.TP +PMDA_CACHE_ACTIVE +Changes +.B every +.B inactive +entry in the cache to be marked +.BR active . +.TP +PMDA_CACHE_INACTIVE +Changes +.B every +.B active +entry in the cache to be marked +.BR inactive . +.TP +PMDA_CACHE_CULL +Remove +.B every +entry from the cache. +.TP +PMDA_CACHE_SIZE +Return the number of entries in the cache (includes +.BR active , +.B inactive +and any culled entries that have not yet been reclaimed). +.TP +PMDA_CACHE_SIZE_ACTIVE +Return the number of +.B active +entries in the cache. +.TP +PMDA_CACHE_SIZE_INACTIVE +Return the number of +.B inactive +entries in the cache. +.TP +PMDA_CACHE_DUMP +Dump the current state of the cache on +.IR stderr . +.TP +PMDA_CACHE_DUMP_ALL +Like PMDA_CACHE_DUMP, but also dump the internal hashing structures +used to support lookup by instance name, lookup by instance identifier and +the collision statistics for ``hint'' hashing from +.BR pmdaCacheStoreKey . +.PP +.B pmdaCacheOp +returns a non-negative value on success, and failure is indicated +by a negative return value (suitable for decoding +with +.BR pmErrStr (3)). +.SH OTHER CONSIDERATIONS +.PP +When the +.B pmdaCache +routines are used for particular instance domain, +.B pmdaInstance (3) +and the instance domain enumeration behind +.BR pmdaFetch (3) +will attempt to extract instance domain information from the cache, thereby avoiding +reference to the +.B pmdaIndom +data structures that have historically been used to define instance domains +and service instance requests. +A PMDA can adopt a hybrid approach and choose to implement some instance +domains via the traditional +.B pmdaIndom +method, and others via the +.B pmdaCache +approach, however attempts to manage the +.I same +instance domain by both +methods will result in the +.B pmdaCache +method silently prevailing. +.PP +If +.B all +instances in a PMDA are to be serviced from a +.B pmdaCache +then a +.B pmdaIndom +is not required, and the +.B pmdaInit (3) +call becomes +.EX + pmdaInit(dp, NULL, 0, metrictab, nmetrics); +.EE +However, the PMDA will need to explicitly initialize the +.B indom +field of the +.B pmDesc +in the +.I metrictab +entries, as this cannot be done by +.BR pmdaInit (3) +if +.I indomtab +is missing entries for the instance domains maintained in the cache. +.PP +Independent of how the instance domain is being maintained, +to refresh an instance domain prior to a fetch or an instance domain +operation, the standard methods of a ``wrapper'' to the +.B pmdaInstance (3) +and +.B pmdaFetch (3) +methods should be used. +.PP +Refer to the +.B simple +PMDA source code for an example use of the +.B pmdaCache +routines. +.PP +When using +.BR pmdaCacheStoreKey , +if there is a desire to ensure the given ``hint'' generates the same +initial instance identifier across all platforms, then the caller +should ensure the endian and word-size issues are considered, e.g. if +the natural data structure used for the +.I key +is an array of 32-bit integers, then +.BR htonl (3) +should be used on each element of the array before calling +.B pmdaCacheStoreKey +or +.BR pmdaCacheLookupKey . +.SH INSTANCE NAME MATCHING +.PP +The following table summarizes the ``short name'' matching semantics +for an instance domain (caches other than PMDA_CACHE_STRINGS style). +.TS +box, center; +l | l | l +l | l | ^ +l | l | l. +name in \fBpmdaCacheLookup\fR result +cache name +_ +foodle foo no match (PM_ERR_INST) +foo foodle no match (PM_ERR_INST) +foo foo match +foo bar foo match on short name (instance identifier) +foo bar foo bar match on full name (instance identifier) +foo foo bar bad match (\-EDOM) +foo bar foo blah bad match (\-EDOM) +.TE +.SH FILES +Cache persistence uses files with names constructed from the +.I indom +within the +.B $PCP_VAR_DIR/config/pmda +directory. +.SH SEE ALSO +.BR BYTEORDER (3), +.BR PMAPI (3), +.BR PMDA (3), +.BR pmdaInit (3), +.BR pmdaInstance (3), +.BR pmdaFetch (3), +.BR pmdaSetFetchCallback (3), +.BR pmErrStr (3) +and +.BR pmGetInDom (3). diff --git a/man/man3/pmdachildren.3 b/man/man3/pmdachildren.3 new file mode 100644 index 0000000..d221001 --- /dev/null +++ b/man/man3/pmdachildren.3 @@ -0,0 +1,132 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000-2004 Silicon Graphics, Inc. All Rights Reserved. +.\" Copyright (c) 2009 Ken McDonell. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMDACHILDREN 3 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmdaChildren\f1 \- translate a PMID to a set of dynamic performance metric names +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.br +#include <pcp/impl.h> +.br +#include <pcp/pmda.h> +.sp +.ad l +.hy 0 +.in +8n +.ti -8n +int pmdaChildren(char *\fIname\fP, int \fItraverse\fP, char\ ***\fIoffspring\fP, int\ **\fIstatus\fP, pmdaExt\ *\fIpmda\fP); +.sp +.in +.hy +.ad +cc ... \-lpcp_pmda \-lpcp +.ft 1 +.SH DESCRIPTION +As part of the Performance Metrics Domain Agent (PMDA) API (see +.BR PMDA (3)), +.BR pmdaChildren +is the generic callback for +returning dynamic metric names (and their status) that are descendants of +.IR name . +.PP +Because implementing dynamic performance metrics requires specific +PMDA support, and the facility is an optional component of a PMDA (most +PMDAs do +.B not +support dynamic performance metrics), +.B pmdaChildren +is a skeleton implementation that returns +.BR PM_ERR_NAME . +.PP +A PMDA that supports dynamic performance metrics will provide a private +callback that replaces +.B pmdaChildren +(by assignment to +.I version.four.children +of the +.I pmdaInterface +structure) +and takes the initial metric +.I name +and returns names via +.IR offspring [] +and the leaf or non-leaf status of each via +.IR status []. +.PP +If +.I traverse +is 0, then the behaviour is akin to +.BR pmGetChildren (3) +and +.IR offspring [] +contains the relative name component for the immediate descendants of +.IR name. +.PP +If +.I traverse +is 1, then the behaviour is akin to +.BR pmTraversePMNS (3) +and +.IR offspring [] +contains the absolute names of all dynamic metrics that are decedents +of +.IR name . +.PP +The resulting list of pointers +.I offspring +.B and +the values +(the names) that the pointers reference will have been +allocated by +.B pmdaChildren +with a single call to +.BR malloc (3C), +and the +caller of +.B pmdaChildren +will call +.BR free (\c +.IR offspring ) +to release the space +when it is no longer required. +The same holds true for the +.I status +array. +.SH DIAGNOSTICS +.B +pmdaChildren +returns +.B PM_ERR_NAME +if the name is not recognized or cannot be translated, +otherwise the number of descendent metric names found. +.SH CAVEAT +The PMDA must be using +.B PMDA_PROTOCOL_4 +or later, as specified in the call to +.BR pmdaDSO (3) +or +.BR pmdaDaemon (3). +.SH SEE ALSO +.BR PMAPI (3), +.BR PMDA (3), +.BR pmdaDaemon (3), +.BR pmdaDSO (3), +.BR pmdaMain (3), +.BR pmGetChildren (3) +and +.BR pmTraversePMNS (3). diff --git a/man/man3/pmdaconnect.3 b/man/man3/pmdaconnect.3 new file mode 100644 index 0000000..bbfe555 --- /dev/null +++ b/man/man3/pmdaconnect.3 @@ -0,0 +1,164 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000-2004 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMDACONNECT 3 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmdaConnect\f1 \- establish a connection between a daemon PMDA and PMCD +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.br +#include <pcp/impl.h> +.br +#include <pcp/pmda.h> +.sp +void pmdaConnect(pmdaInterface *\fIdispatch\fP); +.sp +cc ... \-lpcp_pmda \-lpcp +.ft 1 +.SH DESCRIPTION +.B pmdaConnect +initializes an IPC channel between a +.BR PMDA (3) +and the +.BR pmcd (1) +process on the local host. The type of the connection is dependent on the +.I e_io +field of the +.B pmdaExt +structure: +.TP 15 +.B pmdaPipe +Use +.BR stdin / stdout +to communicate; assumes this is a pipe created by +.B pmcd +before the +.BR PMDA (3) +was launched. +.TP +.B pmdaInet +Assume +.BR pmcd (1) +will establish a connection to an IPv4 internet domain socket set up by the +.BR PMDA (3). +The name or number of the port must be specified in the +.I e_sockname +or +.I e_port +fields of the +.B pmdaExt +structure, respectively. +.TP +.B pmdaIPv6 +Assume +.BR pmcd (1) +will establish a connection to an IPv6 internet domain socket set up by the +.BR PMDA (3). +The name or number of the port must be specified in the +.I e_sockname +or +.I e_port +fields of the +.B pmdaExt +structure, respectively. +.TP +.B pmdaUnix +Assume +.BR pmcd (1) +will establish a connection to a unix domain socket set up by the +.BR PMDA (3). +The port number must be specified in the +.I e_port +field of the +.B pmdaExt structure. +.TP +.B pmdaUnknown +The initial value of +.I e_io +which defaults to using +.BR stdin / stdout . +.PP +The relevant +.B pmdaExt +fields are initialized by +.BR pmdaDaemon (3) +and set by +.BR pmdaGetOpt (3) +or +.BR pmdaGetOptions (3) +so most PMDAs should not need to access or modify them. +.PP +Traditionally most PMDAs have called +.B pmdaConnect +after calls to +.BR pmdaDaemon (3), +.BR pmdaGetOptions (3) +(or +.BR pmdaGetOpt (3)) +and +.BR pmdaInit (3). +If the PMDA requires significant processing at startup to identify +the available metrics and/or instance domains before +.BR pmdaInit (3) +can be called, then it risks timing out during the handshake protocol that +starts as soon as +.BR pmcd (1) +launches the PMDA and does not conclude until +.B pmdaConnect +is called. +In this case, it is advisable to move the +.B pmdaConnect +call, so that it comes +.I after +the call to +.BR pmdaGetOptions (3) +(or +.BR pmdaGetOpt (3)) +and +.I before +the call to +.BR pmdaInit (3). +.SH DIAGNOSTICS +.B pmdaConnect +will log the type of connection made to +.BR pmcd (1) +if the +.BR PMAPI (3) +debug control variable +.RB ( pmDebug ) +has the +.B DBG_TRACE_LIBPMDA +flag set. +.PP +If an error occurs that is unrecoverable, +.I dispatch->status +is set to a value less than 0, otherwise it is zero or positive. +.SH CAVEAT +The PMDA must be using +.B PMDA_INTERFACE_2 +or later, as specified in the call to +.BR pmdaDaemon (3). +.SH SEE ALSO +.BR pmcd (1), +.BR pipe (2), +.BR socket (2), +.BR PMAPI (3), +.BR PMDA (3), +.BR pmdaDaemon (3), +.BR pmdaGetOpt (3), +.BR pmdaGetOptions (3) +and +.BR pmdaInit (3). diff --git a/man/man3/pmdadaemon.3 b/man/man3/pmdadaemon.3 new file mode 100644 index 0000000..e96082d --- /dev/null +++ b/man/man3/pmdadaemon.3 @@ -0,0 +1,108 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000-2004 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMDADAEMON 3 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmdaDaemon\f1 \- initialize the PMDA to run as a daemon +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.br +#include <pcp/impl.h> +.br +#include <pcp/pmda.h> +.sp +.ad l +.hy 0 +.in +8n +.ti -8n +void pmdaDaemon(pmdaInterface *\fIdispatch\fP, int \fIinterface\fP, char\ *\fIname\fP, int\ \fIdomain\fP, char\ *\fIlogfile\fP, char\ *\fIhelptext\fP); +.sp +.in +.hy +.ad +cc ... \-lpcp_pmda \-lpcp +.ft 1 +.SH DESCRIPTION +.B pmdaDaemon +initializes the +.B pmdaInterface +structure to use the +.I interface +extensions assuming the +.BR PMDA (3) +is to be run as a daemon. The +.B pmdaInterface +structure is initialized with: +.TP 15 +.I name +The name of the agent. +.TP +.I domain +The default domain number of the agent which uniquely identifies this PMDA +from other running PMDAs. This may be subsequently changed by a command line +option +.B \-d +(see +.BR pmdaGetOpt (3)). +.TP +.I logfile +The default path to the log file. This may be replaced by the +.B \-l +command line option if using +.BR pmdaGetOpt . +.TP +.I helptext +The default path to the help text (see +.BR pmdaText (3). +This may be replaced by the +.B \-h +command line option if using +.BR pmdaGetOpt (3). +If no help text is installed, or you are not using +.BR pmdaText (3), +then this should be set to NULL. +.PP +The callbacks are initialized to +.BR pmdaProfile (3), +.BR pmdaFetch (3), +.BR pmdaDesc (3), +.BR pmdaText (3), +.BR pmdaInstance (3) +and +.BR pmdaStore (3). +.SH DIAGNOSTICS +.TP 15 +.B Unable to allocate memory for pmdaExt structure +In addition, the +.I dispatch->status +field is set to a value less than zero. +.TP +.BI "PMDA interface version " interface " not supported" +The +.I interface +version is not supported by +.BR pmdaDaemon . +.SH CAVEAT +The PMDA must be using +.B PMDA_INTERFACE_2 +or later. +.SH SEE ALSO +.BR PMAPI (3), +.BR PMDA (3), +.BR pmdaDSO (3), +.BR pmdaGetOpt (3) +and +.BR pmdaText (3). diff --git a/man/man3/pmdadesc.3 b/man/man3/pmdadesc.3 new file mode 100644 index 0000000..a1b0f94 --- /dev/null +++ b/man/man3/pmdadesc.3 @@ -0,0 +1,61 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000-2004 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMDADESC 3 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmdaDesc\f1 \- get the description of a metric from a PMDA +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.br +#include <pcp/impl.h> +.br +#include <pcp/pmda.h> +.sp +int pmdaDesc(pmID \fIpmid\fP, pmDesc *\fIdesc\fP, pmdaExt *\fIpmda\fP); +.sp +cc ... \-lpcp_pmda \-lpcp +.ft 1 +.SH DESCRIPTION +.B pmdaDesc +uses the standard +.BR PMDA (3) +data structures to return the +.B pmDesc +description in +.I desc +for the metric identified by +.IR pmid . +.SH DIAGNOSTICS +If the +.I pmid +does not correspond to any metric supported by this PMDA, +.B pmdaDesc +returns +.BR PM_ERR_PMID . +.SH CAVEAT +The PMDA must be using +.B PMDA_INTERFACE_2 +or later, as specified in the call to +.BR pmdaDSO (3) +or +.BR pmdaDaemon (3). +.SH SEE ALSO +.BR PMAPI (3), +.BR PMDA (3), +.BR pmdaDaemon (3), +.BR pmdaDSO (3) +and +.BR pmLookupDesc (3). diff --git a/man/man3/pmdadso.3 b/man/man3/pmdadso.3 new file mode 100644 index 0000000..655d4e7 --- /dev/null +++ b/man/man3/pmdadso.3 @@ -0,0 +1,113 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000-2004 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMDADSO 3 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmdaDSO\f1 \- initialize the PMDA to run as a DSO +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.br +#include <pcp/impl.h> +.br +#include <pcp/pmda.h> +.sp +.ad l +.hy 0 +.in +8n +.ti -8n +int pmdaDSO(pmdaInterface *\fIdispatch\fP, int \fIinterface\fP, char\ *\fIname\fP, char\ *\fIhelptext\fP); +.sp +.in +.hy +.ad +cc ... \-lpcp_pmda \-lpcp +.ft 1 +.SH DESCRIPTION +.B pmdaDSO +initializes the +.B pmdaInterface +structure to use the +.I interface +extensions, +assuming the +.BR PMDA (3) +is to be run as a DSO. The +.B pmdaInterface +structure is initialized with: +.TP 15 +.I name +The name of the agent. +.TP +.I helptext +The default path to the help text (see +.BR pmdaText (3). +If no help text is installed, or you are not using +.BR pmdaText (3), +then this should be set to NULL. +.PP +The callbacks are initialized to +.BR pmdaProfile (3), +.BR pmdaFetch (3), +.BR pmdaDesc (3), +.BR pmdaText (3), +.BR pmdaInstance (3) +and +.BR pmdaStore (3). +.PP +The +.I interface +structure also contains the +.I domain +of the +.BR PMDA (3), +which is defined in the +.BR pmcd (1) +configuration file. The +.I domain +is used to initialize the metric and instance descriptors (see +.BR pmdaInit (3)). +.SH DIAGNOSTICS +.TP 15 +.B Incompatible version of pmcd detected +When +.BR pmcd (1) +creates the +.B pmdaInterface +structure, the +.I dispatch.comm.version +field is set to the highest protocol that +.BR pmcd (1) +understands. This message indicates that the +.BR pmcd (1) +process does not understand the protocol used by +.BR pmdaDSO . +.TP +.B Unable to allocate memory for pmdaExt structure +In addition, +.I dispatch->status +is set to a value less than zero. +.SH CAVEAT +The PMDA must be using +.B PMDA_INTERFACE_2 +or later. +.SH SEE ALSO +.BR pmcd (1), +.BR PMAPI (3), +.BR PMDA (3), +.BR pmdaDaemon (3), +.BR pmdaInit (3) +and +.BR pmdaText (3). diff --git a/man/man3/pmdaeventarray.3 b/man/man3/pmdaeventarray.3 new file mode 100644 index 0000000..1951edb --- /dev/null +++ b/man/man3/pmdaeventarray.3 @@ -0,0 +1,311 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2014 Red Hat. +.\" Copyright (c) 2010 Ken McDonell. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMDAEVENTARRAY 3 "PCP" "Performance Co-Pilot" +.SH NAME +.ad l +\f3pmdaEventNewArray\f1, +\f3pmdaEventResetArray\f1, +\f3pmdaEventReleaseArray\f1, +\f3pmdaEventAddRecord\f1, +\f3pmdaEventAddMissedRecord\f1, +\f3pmdaEventAddParam\f1, +\f3pmdaEventGetAddr\f1, +\f3pmdaEventNewHighResArray\f1, +\f3pmdaEventResetHighResArray\f1, +\f3pmdaEventReleaseHighResArray\f1, +\f3pmdaEventAddHighResRecord\f1, +\f3pmdaEventAddHighResMissedRecord\f1, +\f3pmdaEventHighResAddParam\f1, +\f3pmdaEventHighResGetAddr\f1 \- utilities for PMDAs to build packed arrays of event records +.br +.ad +.SH "C SYNOPSIS" +.ft 3 +.nf +#include <pcp/pmapi.h> +#include <pcp/impl.h> +#include <pcp/pmda.h> +.fi +.sp +.ad l +.hy 0 +.in +8n +.ti -8n +int pmdaEventNewArray(void); +.br +.ti -8n +int pmdaEventResetArray(int \fIidx\fP); +.br +.ti -8n +int pmdaEventReleaseArray(int \fIidx\fP); +.br +.ti -8n +int pmdaEventAddRecord(int \fIidx\fP, struct timeval *\fItp\fP, int\ \fIflags\fP); +.br +.ti -8n +int pmdaEventAddMissedRecord(int \fIidx\fP, struct timeval *\fItp\fP, int\ \fInmissed\fP); +.br +.ti -8n +int pmdaEventAddParam(int \fIidx\fP, pmID \fIpmid\fP, int \fItype\fP, pmAtomValue\ *\fIavp\fP); +.br +.ti -8n +pmEventArray *pmdaEventGetAddr(int \fIidx\fP); +.sp +.in +.hy +.ad l +.hy 0 +.in +8n +.ti -8n +int pmdaEventNewHighResArray(void); +.br +.ti -8n +int pmdaEventResetHighResArray(int \fIidx\fP); +.br +.ti -8n +int pmdaEventReleaseHighResArray(int \fIidx\fP); +.br +.ti -8n +int pmdaEventAddHighResRecord(int \fIidx\fP, struct timespec *\fIts\fP, int\ \fIflags\fP); +.br +.ti -8n +int pmdaEventAddHighResMissedRecord(int \fIidx\fP, struct timespec *\fIts\fP, int\ \fInmissed\fP); +.br +.ti -8n +int pmdaEventHighResAddParam(int \fIidx\fP, pmID \fIpmid\fP, int \fItype\fP, pmAtomValue\ *\fIavp\fP); +.br +.ti -8n +pmHighResEventArray *pmdaEventHighResGetAddr(int \fIidx\fP); +.sp +.in +.hy +.ad +cc ... \-lpcp +.ft 1 +.SH DESCRIPTION +.de CW +.ie t \f(CW\\$1\f1\\$2 +.el \fI\\$1\f1\\$2 +.. +A Performance Metrics Domain Agent (PMDA) that wishes to export +event records (or trace records) is encouraged to use a metric of +either type +.B PM_TYPE_EVENT +or +.B PM_TYPE_HIGHRES_EVENT +to encode a group of event records into a single packed array. +.PP +The only difference between the two metric types is the resolution +of the timestamp associated with each \- in high resolution form it +is nanosecond scale (see +.BR clock_gettime (2)), +otherwise it is microseconds (see +.BR gettimeofday (2)). +For simplicity, we will only refer to the lower resolution API and +data structures hereafter \- however, the higher resolution variants +are all named similarly and are used in the same way. +.PP +The packed array of event records format is defined in +.I <pcp/pmapi.h> +and consists of a +.B pmEventArray +structure containing a variable number of +.B pmEventRecord +structures, each of which contains a variable number of +.B pmEventParameter +structures, which in turn may contain a variable length value for +each parameter of each event record. +.PP +The higher resolution equivalents are defined in the same location, +and the structures are named the same. +Note that the +.B pmEventParameter +structure has no timestamp associated with it, hence it this does not +have a high resolution counterpart. +.PP +The routines described here are designed to assist the PMDA developer +in building a packed array of event records, and managing all of the +memory allocations required to hold each instance of an array of event +records in a contiguous buffer. Normal use would be as part of PMDA's +.B pmdaFetchCallBack +method. +.PP +.B pmdaEventNewArray +is used to create a new event array. The return value is a small integer that +is used as the +.I idx +parameter to the other routines to identify a specific event array. +If needed, a PMDA can create and use multiple event arrays. +.PP +To start a new cycle and refill an event array from the beginning, call +.BR pmdaEventResetArray . +.PP +If the PMDA has finished with an event array, +.B pmdaEventReleaseArray +may be used to release the underlying storage and ``close'' the event +array so that subsequent attempts to use +.I idx +will return +.BR PM_ERR_NOCONTEXT . +.PP +To start a new event record, use +.BR pmdaEventAddRecord . +The timestamp for the event record is given via +.I tp +and the +.I flags +parameter may be used to set the control field that determines the +type of the event record \- +.I flags +may be the bit-wise ``or'' of one or more of the +.B PM_EVENT_FLAG_* +values defined in +.I <pcp/pmapi.h> +(but note that +.B PM_EVENT_FLAG_MISSED +should not be used in this context). +.PP +If event records have been missed, either because the PMDA cannot keep +up or because the PMAPI client cannot keep up, then +.B pmdaEventAddMissedRecord +may be used. +.I +idx +and +.I tp +have the same meaning as for +.B pmdaEventAddRecord +and +.I nmissed +is the number of event records that have been missed at this point +in the time-series of event records. +.B pmdaEventAddMissedRecord +may be called multiple times for a single batch of event records +if there are more than one ``missed event record'' episode. +.PP +Once an event record has been started by calling +.BR pmdaEventAddRecord , +one or more event parameters may be added using +.BR pmdaEventAddParam . +The +.I pmid +and +.I type +parameters decribe the PMID of the parameter and the data type +(one of the +.B PM_TYPE_* +values from +.IR <pcp/pmapi.h> ) +of the value that is passed via +.IR avp . +.I type +should one where the size of the value is implied by the +.I type +or by the length of a string value (for +.BR PM_TYPE_STRING ) +or encoded within +.I avp->vbp +(for +.BR PM_TYPE_AGGREGATE ). +.PP +Once the packed array has been constructed, +.B pmdaEventGetAddr +should be used to initialize the +.B ea_type +and +.B ea_len +fields at the start of the +.B pmEventArray +and return the base address of the event array +that is assigned to the +.B vp +field of the +.B pmAtomValue +structure that the +.B pmdaFetchCallBack +method should return. +.SH EXAMPLE +The following skeletal code shows how these routines might be used. +.PP +.ft CW +.ps -1 +.nf +int sts; +int myarray; +int first = 1; +pmEventArray eap; + +if (first) { + first = 0; + if ((myarray = pmdaEventNewArray()) < 0) { + // report error and fail + } +} + +pmdaEventResetArray(myarray); + +// loop over all event records to be exported +\&... { + struct timeval stamp; + int flags; + + // establish timestamp and set flags to 0 or some combination + // of PM_EVENT_FLAG_POINT, PM_EVENT_FLAG_START, PM_EVENT_FLAG_ID, + // etc + if ((sts = pmdaEventAddRecord(myarray, &stamp, flags)) < 0) { + // report error and fail + } + + // loop over all parameters for this event record + ... { + pmID pmid; + int type; + pmAtomValue atom; + + // construct pmid, type and atom for the parameter and + // its value + if ((sts = pmdaEventAddParam(myarray, pmid, type, &atom)) < 0) { + // report error and fail + } + } + + // if some event records were missed (could be at the start + // of the exported set, or at the end, or in the middle, or + // a combination of multiple missed record episodes) + ... { + int nmiss; + struct timeval stamp; + + if ((sts = pmdaEventAddMissedRecord(myarray, &stamp, nmiss)) < 0) { + // report error and fail + } + } +} + +// finish up +eap = pmdaEventGetAddr(myarray); +.fi +.ps +.ft +.SH SEE ALSO +.BR clock_gettime (2), +.BR gettimeofday (2), +.BR pmdaEventNewQueue (3), +.BR pmdaEventNewClient (3), +.BR PMDA (3) +and +.BR pmEventFlagsStr (3). diff --git a/man/man3/pmdaeventclient.3 b/man/man3/pmdaeventclient.3 new file mode 100644 index 0000000..5230d0b --- /dev/null +++ b/man/man3/pmdaeventclient.3 @@ -0,0 +1,95 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2013 Red Hat. +.\" Copyright (c) 2011 Nathan Scott. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMDAEVENTCLIENT 3 "PCP" "Performance Co-Pilot" +.SH NAME +.ad l +\f3pmdaEventNewClient\f1, +\f3pmdaEventEndClient\f1, +\f3pmdaEventClients\f1 \- client context tracking interfaces for event queues +.br +.ad +.SH "C SYNOPSIS" +.ft 3 +.nf +#include <pcp/pmapi.h> +#include <pcp/impl.h> +#include <pcp/pmda.h> +.fi +.sp +.ad l +.hy 0 +.in +8n +.ti -8n +int pmdaEventNewClient(int \fIcontext\fP); +.br +.ti -8n +int pmdaEventEndClient(int \fIcontext\fP); +.br +.ti -8n +int pmdaEventClients(pmAtomValue *\fIavp\fP); +.sp +.in +.hy +.ad +cc ... \-lpcp_pmda \-lpcp +.ft 1 +.SH DESCRIPTION +.de CW +.ie t \f(CW\\$1\f1\\$2 +.el \fI\\$1\f1\\$2 +.. +A Performance Metrics Domain Agent (PMDA) that exports event records +needs to track which clients are connected to it, in order that it can +track which events have been sent to which clients so far. +Only once an event has been sent to all monitoring tools that registered +an interest can the event be discarded and any memory reclaimed. +.PP +The +.BR PMDA (3) +library provides callback routines for PMDA developers to provide custom +handling of client connections and disconnections. +If the PMDA is making use of the event queueing mechanism provided by +.BR pmdaEventNewQueue (3) +and friends, client connections and disconnections must be tracked via +calls to +.B pmdaEventNewClient +and +.B pmdaEventEndClient +respectively. +This allows the library to keep track of when events can be discarded +from a queue, for example, for the +.I context +specified. +This parameter is passed into the e_endCallBack function directly, +and for other callback functions is available via the e_context field +of the pmdaExt structure. +Additionally, it can be queried at any time using +.BR pmdaGetContext (3). +.PP +Sometimes it is useful for the PMDA to export a metric indicating the +current count of attached clients \- this is available using the +.B pmdaEventClients +routine, which will fill in the +.I avp +pmAtomValue structure on behalf of a PMDA fetch callback routine. +.SH SEE ALSO +.BR pmdaEventNewArray (3), +.BR pmdaEventNewQueue (3), +.BR PMAPI (3), +.BR PMDA (3) +and +.BR pmEventFlagsStr (3). diff --git a/man/man3/pmdaeventqueue.3 b/man/man3/pmdaeventqueue.3 new file mode 100644 index 0000000..43f243b --- /dev/null +++ b/man/man3/pmdaeventqueue.3 @@ -0,0 +1,190 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2011-2012 Nathan Scott. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMDAEVENTQUEUE 3 "PCP" "Performance Co-Pilot" +.SH NAME +.ad l +\f3pmdaEventNewQueue\f1, +\f3pmdaEventNewActiveQueue\f1, +\f3pmdaEventQueueHandle\f1, +\f3pmdaEventQueueAppend\f1, +\f3pmdaEventQueueRecords\f1, +\f3pmdaEventQueueClients\f1, +\f3pmdaEventQueueCounter\f1, +\f3pmdaEventQueueBytes\f1, +\f3pmdaEventQueueMemory\f1 \- utilities for PMDAs managing event queues +.br +.ad +.SH "C SYNOPSIS" +.ft 3 +.nf +#include <pcp/pmapi.h> +#include <pcp/impl.h> +#include <pcp/pmda.h> +.fi +.sp +.ad l +.hy 0 +.in +8n +.ti -8n +int pmdaEventNewQueue(const char *\fIname\fP, size_t \fImaxmem\fP); +.br +.ti -8n +int pmdaEventNewActiveQueue(const char *\fIname\fP, size_t \fImaxmem\fP, int \fInclients\fP); +.br +.ti -8n +int pmdaEventQueueHandle(const char *\fIname\fP); +.br +.ti -8n +int pmdaEventQueueAppend(int \fIhandle\fP, void *\fIbuffer\fP, size_t \fIbytes\fP, struct timeval *\fItv\fP); +.br +.sp +.in +.hy +.ad +.in +8n +.ti -8n +typedef int (*pmdaEventDecodeCallBack)(int, void *, int, struct timeval *, void *); +.br +.ti -8n +int pmdaEventQueueRecords(int \fIhandle\fP, pmAtomValue *\fIavp\fP, int \fIcontext\fP, pmdaEventDecodeCallBack \fIdecoder\fP, void *\fIdata\fP); +.br +.ti -8n +int pmdaEventQueueClients(int \fIhandle\fP, pmAtomValue *\fIavp\fP); +.br +.ti -8n +int pmdaEventQueueCounter(int \fIhandle\fP, pmAtomValue *\fIavp\fP); +.br +.ti -8n +int pmdaEventQueueBytes(int \fIhandle\fP, pmAtomValue *\fIavp\fP); +.br +.ti -8n +int pmdaEventQueueMemory(int \fIhandle\fP, pmAtomValue *\fIavp\fP); +.sp +.in +.hy +.ad +cc ... \-lpcp_pmda \-lpcp +.ft 1 +.SH DESCRIPTION +.de CW +.ie t \f(CW\\$1\f1\\$2 +.el \fI\\$1\f1\\$2 +.. +A Performance Metrics Domain Agent (PMDA) that exports event records +must effectively act an event multiplexer. +Events consumed by the PMDA may have to be forwarded on to any number +of monitoring tools (or "client contexts"). +These tools may be requesting events at different sampling intervals, +and are very unlikely to request an event at the exact moment it arrives +at the PMDA, making some form of event buffering and queueing scheme a +necessity. +Events must be held by the PMDA until either all registered clients +have been sent them, or until a memory limit has been reached by the +PMDA at which point it must discard older events as new ones arrive. +.PP +The routines described here are designed to assist the PMDA developer +in managing both client contexts and queues of events at a high level. +These fit logically above lower level primitives, such as those +described in +.BR pmdaEventNewArray (3), +and shield the average PMDA from the details of directly building event +record arrays for individual client contexts. +.PP +The PMDA registers a new queue of events using either +.B pmdaEventNewQueue +or +.BR pmdaEventNewActiveQueue . +These are passed an identifying +.I name +(for diagnostic purposes, and for subsequent lookup by +.BR pmdaEventQueueLookup ) +and +.IR maxmem , +an upper bound on the memory (in bytes) that can be consumed by events +in this queue, before beginning to discard them (resulting in "missed" +events for any client that has not kept up). +If a queue is dynamically allocated (such that the PMDA may already have +clients connected) the +.B pmdaEventNewActiveQueue +interface should be used, with the additional +.I numclients +parameter indicating the count of active client connections. +The return is a negative error code on failure, suitable for decoding +by the +.BR pmErrStr (3) +routine. +Any non-negative value indicates success, and provides a +.I handle +suitable for passing into the other API routines. +.PP +For each new event received by the PMDA, the +.B pmdaEventQueueAppend +routine should be called, placing that event into the queue identified +by +.IR handle . +The event itself must be contained in the passed in +.IR buffer , +having +.I bytes +length. +The timestamp associated with the event (time at which the event +occurred) is passed in via the final +.I tv +parameter. +.PP +In the PMDAs specific implementation of its fetch callback, when values +for an event metric have been requested, the +.BR pmdaEventQueueRecords +routine should be used. +It is passed the queue +.I handle +and the +.I avp +pmAtomValue structure to fill with event records, for the client making +that fetch request (identified by the +.I context +parameter). +Finally, the PMDA must also pass in an event decoding routine, which is +responsible for decoding the fields of a single event into the individual +event parameters of that event. +The +.I data +parameter is an opaque cookie that can be used to pass situation-specific +information into each +.I decoder +invocation. +.PP +Under some situations it is useful for the PMDA to export state about +the queues under its control. +The accessor routines \- +.BR pmdaEventQueueClients , +.BR pmdaEventQueueCounter , +.BR pmdaEventQueueBytes +and +.BR pmdaEventQueueMemory +provide a mechanism for querying a queue by its +.I handle +and filling in a +.B pmAtomValue +structure that the +.B pmdaFetchCallBack +method should return. +.SH SEE ALSO +.BR PMAPI (3), +.BR PMDA (3), +.BR pmdaEventNewClient (3) +and +.BR pmdaEventNewArray (3). diff --git a/man/man3/pmdafetch.3 b/man/man3/pmdafetch.3 new file mode 100644 index 0000000..63a083b --- /dev/null +++ b/man/man3/pmdafetch.3 @@ -0,0 +1,397 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000-2004 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMDAFETCH 3 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmdaFetch\f1, +\f3pmdaSetFetchCallBack\f1 \- fill a pmResult structure with the requested metric values +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.br +#include <pcp/impl.h> +.br +#include <pcp/pmda.h> +.sp +.ad l +.hy 0 +.in +8n +.ti -8n +int pmdaFetch(int \fInumpmid\fP, pmID *\fIpmidlist\fP, pmResult **\fIresp\fP, pmdaExt\ *\fIpmda\fP); +.br +.ti -8n +void pmdaSetFetchCallBack(pmdaInterface *\fIdispatch\fP, pmdaFetchCallBack\ \fIcallback\fP); +.sp +.in +.hy +.ad +cc ... \-lpcp_pmda \-lpcp +.ft 1 +.SH DESCRIPTION +.B pmdaFetch +is a generic callback used by a +.BR PMDA (3) +to process a fetch request from +.BR pmcd (1). +The request from +.B pmcd +is initiated by a client calling +.BR pmFetch (3). +.PP +This is the only generic callback in +.I libpcp_pmda +(see +.BR PMDA (3)) +that is incomplete, requiring +a further +.B pmdaFetchCallBack +method of its own. The additional callback should be registered using +.B pmdaSetFetchCallBack +and the +.B pmdaFetchCallBack +method has the following prototype: +.nf +.ft CW +.ps -1 +int func(pmdaMetric *mdesc, unsigned int inst, pmAtomValue *avp) +.ps +.ft +.fi +.PP +.B pmdaFetch +will allocate and resize the +.I resp +result structure, to store values for the +.I numpmid +metrics listed in +.IR pmidlist . +.PP +For each instance listed in the profile (see +.BR pmdaProfile (3)) +of each metric listed in +.IR pmidlist , +the +.B pmdaFetchCallBack +method is called to fill the +.B pmAtomValue +structure identified by +.I avp +with a value for a specific metric-instance pair identified +by the metric descriptor +.I mdesc +and the instance +.IR inst . +This value is then copied into the +.B pmResult +structure. +.PP +The +.B pmdaFetchCallBack +method should return a value less than zero for an error, and the most +likely cases would be +.B PM_ERR_PMID +if the metric identified by +.I mdesc +is not known to the method, or +.B PM_ERR_INST +if the method believes the instance +.I inst +is not known for the metric identified by +.IR mdesc . +.PP +The success error codes depend on the version of +.B PMDA_INTERFACE +the PMDA is using. +.PP +If the PMDA is using +.B PMDA_INTERFACE_2 +then on success the +.B pmdaFetchCallBack +method should return +.BR 0 . +.PP +If the PMDA is using +.B PMDA_INTERFACE_3 +or +.B PMDA_INTERFACE_4 +then on success the +.B pmdaFetchCallBack +method should return +.B 1 +if a value is returned via +.IR avp , +else +.B 0 +if no values are currently available for the requested metric-instance pair +although +.I mdesc +and +.I inst +both seem reasonable. +.PP +If the PMDA is using +.B PMDA_INTERFACE_5 +or later then on success the +.B pmdaFetchCallBack +method should return +.B PMDA_FETCH_STATIC +(\c +.BR 1 ) +if the value returned via +.I avp +can be ignored by +.B pmdaFetch +once it has been copied into the +.B pmResult +structure, else +.B PMDA_FETCH_DYNAMIC +(\c +.BR 2 ) +if the value returned via +.I avp +uses the either the +.B vp +or +.B cp +fields of the +.B pmAtomValue +and the associated value (buffer) was allocated using +one of +.BR malloc (3), +.BR calloc (3), +.BR realloc (3), +.B strdup (3) +etc. and +.B pmdaFetch +should release the memory by calling +.IR free (3) +once a new buffer has been allocated and the value copied, +else +.B PMDA_FETCH_NOVALUES +(\c +.BR 0 ) +if no values are currently available for the requested metric-instance pair +although +.I mdesc +and +.I inst +both seem reasonable. +.PP +If the +.B pmdaFetchCallBack +method returns a value for an instance of a metric of type +.B PM_TYPE_STRING +or +.B PM_TYPE_AGGREGATE +some special care is needed \(en +the method should either use a static buffer, set +.I avp->cp +or +.I avp->vp +to the address of the buffer and return +.BR PMDA_FETCH_STATIC , +or use a dynamically allocated buffer, keep a static reference to +the buffer's address, return +.B PMDA_FETCH_STATIC +and +.I free (3) +or +.I realloc (3) +or reuse the buffer the next time the +.B pmdaFetchCallBack +method is called, +else use a dynamically allocated buffer +and return +.BR PMDA_FETCH_DYNAMIC . +.SH EXAMPLE +.PP +The following code fragments are for a hypothetical PMDA has with metrics (A, B, C and D) and an instance +domain (X) with two instances (X1 and X2). The instance domain and +metrics description tables (see +.BR pmdaInit (3)) +could be defined as: +.PP +.nf +.ft CW +.ps -1 +.in +0.5i +static pmdaInstid _X[] = { + { 0, "X1" }, { 1, "X2" } +}; +.sp 0.5v +static pmdaIndom indomtab[] = { +#define X_INDOM 0 + { 0, 2, _X }, +}; +.sp 0.5v +static pmdaMetric metrictab[] = { +/* A */ + { (void *)0, + { PMDA_PMID(0,0), PM_TYPE_32, PM_INDOM_NULL, + PM_SEM_INSTANT, {0,0,0,0,0,0} }, }, +/* B */ + { (void *)0, + { PMDA_PMID(0,1), PM_TYPE_DOUBLE, X_INDOM, + PM_SEM_INSTANT, {0,1,0,0,PM_TIME_SEC,0} }, }, +/* C */ + { (void *)0, + { PMDA_PMID(0,2), PM_TYPE_STRING, PM_INDOM_NULL, + PM_SEM_INSTANT, {0,0,0,0,0,0} }, }, +/* D */ + { (void *)0, + { PMDA_PMID(0,3), PM_TYPE_STRING, PM_INDOM_NULL, + PM_SEM_INSTANT, {0,0,0,0,0,0} }, }, +}; +.in +.ps +.ft +.fi +.br +.PP +A +.B pmdaFetchCallBack +method to be called from +.B pmdaFetch +could be defined as: +.PP +.nf +.ft CW +.ps -1 +.in +0.5i +int +myFetchCallBack(pmdaMetric *mdesc, unsigned int inst, pmAtomValue *avp) +{ + static char sbuf[20]; // reuse this buffer + char *dbuf; // malloc'd +.sp 0.5v + switch (pmid_item(mdesc->m_desc.pmid)) { + case 0: + /* assign some value for metric A */; + avp->l = ... + break; + case 1: + switch (inst) { + case 0: + /* assign a value for metric B, instance X1 */; + avp->d = ... + break; + case 1: + /* assign a value for metric B, instance X2 */; + avp->d = ... + break; + default: + return PM_ERR_INST; + } + case 2: + /* place value for metric C in dbuf[] */ + memcpy(dbuf, ...); + avp->cp = dbuf; + break; + case 3: + avp->cp = (char *)malloc(somesize); + /* place value in avp->cp */ + snprintf(avp->cp, somesize, ...); + return PMDA_FETCH_DYNAMIC; +.sp 0.5v + default: + return PM_ERR_PMID; + } + return PMDA_FETCH_STATIC; +} +.in +.ps +.ft +.fi +.PP +.SH DIAGNOSTICS +The following error messages indicate that there is discrepancy between the +namespace, +.B pmdaMetric +and +.B pmdaIndom +tables passed to +.BR pmdaInit (3), +and the registered fetch callback: +.TP 15 +.BI "pmdaFetch: Requested metric " metric " is not defined" +A requested metric +.I metric +is not listed in the +.B pmdaMetric +table. The namespace for this +.BR PMDA (3) +may contain additional metrics. +.TP +.BI "pmdaFetch: PMID " pmid " not handled by fetch callback" +The +.B pmdaFetchCallBack +method has returned +.BR PM_ERR_PMID . +This indicates that a metric may be listed in the +.B pmdaMetric +table, but is not supported by the callback method. +.TP +.BI "pmdaFetch: Instance " inst " of PMID " pmid " not handled by fetch callback" +The +.B pmdaFetchCallBack +method has returned +.BR PM_ERR_INST . +This indicates that an instance of metric is listed in the +.B pmdaIndom +table, but is not supported by the callback method. +.TP +.B pmdaFetch: Fetch callback error: +The +.B pmdaFetchCallBack +method returned a result other than +.BR PMDA_FETCH_NOVALUES , +.BR PMDA_FETCH_STATIC , +.BR PMDA_FETCH_DYNAMIC , +.B PM_ERR_PMID +or +.BR PM_ERR_INST . +.TP +.BI "pmdaFetch: Descriptor type (" type ") for metric " pmid " is bad" +The data type +.I type +specified for the metric +.I pmid +in the +.B pmdaMetric +table is illegal. +.PP +.B pmdaFetch +will return +.B \-errno +if an error occurred while allocating the +.B pmResult +structure or copying the value from the +.BR pmAtomValue . +.SH CAVEAT +The PMDA must be using +.B PMDA_INTERFACE_2 +or later, as specified in the call to +.BR pmdaDSO (3) +or +.BR pmdaDaemon (3). +.SH SEE ALSO +.BR pmcd (1), +.BR PMAPI (3), +.BR PMDA (3), +.BR pmdaDaemon (3), +.BR pmdaDSO (3), +.BR pmdaInit (3) +and +.BR pmFetch (3). diff --git a/man/man3/pmdagetoptions.3 b/man/man3/pmdagetoptions.3 new file mode 100644 index 0000000..cc4c419 --- /dev/null +++ b/man/man3/pmdagetoptions.3 @@ -0,0 +1,239 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2014 Red Hat. +.\" Copyright (c) 2000-2004 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMDAGETOPTIONS 3 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmdaGetOpt\f1, +\f3pmdaGetOptions\f1 \- get options from arguments, parsing generic PMDA options +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.br +#include <pcp/impl.h> +.br +#include <pcp/pmda.h> +.sp +.ad l +.hy 0 +.in +8n +.ti -8n +int pmdaGetOptions(int \fIargc\fP, char *const *\fIargv\fP, pmdaOptions *\fIopts\fP, pmdaInterface\ *\fIdispatch\fP); +.sp +.in +.hy +.ad +.ad l +.hy 0 +.in +8n +.ti -8n +int pmdaGetOpt(int \fIargc\fP, char *const *\fIargv\fP, const\ char\ *\fIoptstring\fP, pmdaInterface\ *\fIdispatch\fP, int\ *\fIerr\fP); +.sp +.in +.hy +.ad +cc ... \-lpcp_pmda \-lpcp +.ft 1 +.SH DESCRIPTION +These functions are wrappers for +.BR pmgetopt_r (3). +The behavior of each function is that certain options are +assumed to have a predefined behavior which initializes +several fields in the +.B pmdaInterface +structure. +The +.B pmdaGetOptions +interface allows both short and long options to be given, +whereas +.B pmdaGetOpt +allows for short form options only. +.PP +The options that both +.B pmdaGetOptions +and +.B pmdaGetOpt +will trap are: +.TP 15 +.BI \-D trace +Set the +.BR PMAPI (3) +debug control variable +.RB ( pmDebug ) +to +.IR trace . +Used for controlling levels of trace output while debugging. +.TP +.BI \-d domain +Set the +.I domain +number of this agent. +.TP +.BI \-h helpfile +Obtain the help text (see +.BR pmdaText (3)) +for the metrics from this file rather than from the path specified with +.BR pmdaDSO (3) +or +.BR pmdaDaemon (3). +.TP +.BI \-i port +Expect PMCD to connect on inet +.I port +(number or name). +.TP +.BI \-6 port +Expect PMCD to connect on ipv6 +.I port +(number or name). +.TP +.BI \-l logfile +Redirect diagnostics and trace output to +.IR logfile . +.TP +.B \-p +Expect PMCD to supply stdin/stdout pipe. +.TP +.BI \-u socket +Expect PMCD to connect on unix domain +.IR socket . +.PP +The +.B pmdaGetOptions +interface will also capture the following options, and store them +within the +.I opts +parameter: +.TP 15 +.BI \-U username +Set the user account name under which the PMDA should execute. +.PP +Only one of +.BR \-i , +.BR \-6 , +.BR \-p +and +.B \-u +may be specified. If none of these three options is given, a pipe +.RB ( \-p ) +is assumed. When these options are encountered by +.BR pmdaGetOpt , +the option is processed and the next option is examined. Therefore, +.B pmdaGetOpt +will only return when an option other than those listed above is found, or the +end of the list is reached. The returned value will be the argument or +EOF, respectively. +.PP +A PMDA can control which of these options the program will accept with +either the +.I opts +or +.I optstring +argument. To accept all the options, the PMDA should call +.B pmdaGetOptions +with the short_options field of the +.I opts +structure set to the PMDA_OPTIONS macro, +or +.B pmdaGetOpt +with the option string "D:d:h:i:l:pu:". +Any PMDA specific options should be added to these strings in the style of +.BR getopt (3), +and will be returned by both +.B pmdaGetOptions +and +.B pmdaGetOpt +if encountered. +.PP +When a command line option usage error is detected in the +.B pmdaGetOptions +interface, the error field of the +.I opts +structure will contain a non-zero error count. +.PP +.B pmdaGetOpt +takes a pointer to an int, +.IR err , +which is used as an error count. This variable should be initialized to zero +before +.B pmdaGetOpt +is first called, and tested when +.B pmdaGetOpt +returns EOF. +.PP +Neither +.B pmdaGetOptions +nor +.B pmdaGetOpt +modify their +.I argc +or +.I argv +parameters. +.PP +The global variables used by the system +.B getopt (3) +interface may also be used by the caller of +.B pmdaGetOpt +within the argument parsing loop. +.PP +On the other hand, the +.B pmdaGetOptions +interface does not utilize global variables at all (neither reading +nor modifying them). +Instead, these variables can be access via the +.I opts +fields of the same name. +.SH DIAGNOSTICS +Both +.B pmdaGetOptions +and +.B pmdaGetOpt +will display the same error messages as +.BR getopt . +.SH CAVEAT +The options +.BR \-D , +.BR \-d , +.BR \-i , +.BR \-l , +.BR \-p +and +.B \-u +cannot be reused for other purposes by the PMDA, unless using the +.I override +method provided by the +.B pmdaGetOptions +interface, which operates in the same way as described for the +.BR pmGetOptions (3) +interface used by PMAPI client tools. +.PP +The PMDA must be using +.B PMDA_INTERFACE_2 +or later, as specified in the call to +.BR pmdaDSO (3) +or +.BR pmdaDaemon (3). +.SH SEE ALSO +.BR pmdbg (1), +.BR getopt (3), +.BR pmgetopt_r (3), +.BR pmGetOptions (3), +.BR PMAPI (3), +.BR PMDA (3), +.BR pmdaDaemon (3), +.BR pmdaDSO (3) +and +.BR pmdaText (3). diff --git a/man/man3/pmdahelp.3 b/man/man3/pmdahelp.3 new file mode 100644 index 0000000..5d517f0 --- /dev/null +++ b/man/man3/pmdahelp.3 @@ -0,0 +1,102 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000-2004 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMDAHELP 3 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmdaOpenHelp\f1, +\f3pmdaGetHelp\f1, +\f3pmdaGetInDomHelp\f1, +\f3pmdaCloseHelp\f1 \- help text support for a PMDA +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.br +#include <pcp/impl.h> +.br +#include <pcp/pmda.h> +.sp +int pmdaOpenHelp(char *\fIfname\fP); +.br +char *pmdaGetHelp(int \fIhandle\fP, pmID \fIpmid\fP, int \fItype\fP); +.br +char *pmdaGetInDomHelp(int \fIhandle\fP, pmInDom \fIindom\fP, int \fItype\fP); +.br +void pmdaCloseHelp(int \fIhandle\fP); +.sp +cc ... \-lpcp_pmda \-lpcp +.ft 1 +.SH DESCRIPTION +As part of the Performance Metrics Domain Agent (PMDA) API (see +.BR PMDA (3)), +this group of routines is used to implement the processing of a PMDA's metric +help information. +.PP +These routines are really intended for internal use, and should not +need to be called directly from any PMDA code. +.PP +Briefly, the base name of the help text file (as created by +.BR newhelp (1)) +is passed in via a +.B \-h +command line option for a daemon PMDA or as an argument to +.BR pmdaDaemon (3) +or +.BR pmdaDSO (3). +Then +.B pmdaOpenHelp +is called from +.BR pmdaInit (3) +and returns a +.I handle +that is used in subsequent calls to identify a particular help +text collection (each PMDA typically has only one such collection). +.PP +Requests for help text are passed to +.BR pmdaText (3) +which calls +.B pmdaGetHelp +or +.B pmdaGetInDomHelp +as required. +.PP +Other than error cases in +.BR pmdaOpenHelp , +.B pmdaCloseHelp +is not called. +.SH DIAGNOSTICS +.B pmdaOpenHelp +returns a negative value for failure, suitable for decoding with +.BR pmErrStr (3). +.B pmdaGetHelp +and +.B pmdaGetInDomHelp +return NULL if the corresponding help text does not exist. +.SH CAVEAT +The PMDA must be using +.B PMDA_PROTOCOL_2 +or later, as specified in the call to +.BR pmdaDSO (3) +or +.BR pmdaDaemon (3). +.SH SEE ALSO +.BR newhelp (1), +.BR PMAPI (3), +.BR PMDA (3), +.BR pmdaDaemon (3), +.BR pmdaDSO (3), +.BR pmdaInit (3), +.BR pmdaText (3) +and +.BR pmErrStr (3). diff --git a/man/man3/pmdainit.3 b/man/man3/pmdainit.3 new file mode 100644 index 0000000..1a53e37 --- /dev/null +++ b/man/man3/pmdainit.3 @@ -0,0 +1,299 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2013 Red Hat. +.\" Copyright (c) 2000-2004 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMDAINIT 3 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmdaInit\f1, +\f3pmdaRehash\f1, +\f3pmdaSetFlags\f1 \- initialize a PMDA +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.br +#include <pcp/impl.h> +.br +#include <pcp/pmda.h> +.sp +.ad l +.hy 0 +.in +8n +.ti -8n +void pmdaInit(pmdaInterface *\fIdispatch\fP, pmdaIndom *\fIindoms\fP, int\ \fInindoms\fP, pmdaMetric\ *\fImetrics\fP, int\ \fInmetrics\fP); +.br +.ti -8n +void pmdaRehash(pmdaExt *\fIpmda\fP, pmdaMetric\ *\fImetrics\fP, int\ \fInmetrics\fP); +.br +.ti -8n +void pmdaSetFlags(pmdaInterface *\fIdispatch\fP, int \fIflags\fP); +.sp +.in +.hy +.ad +cc ... \-lpcp_pmda \-lpcp +.ft 1 +.SH DESCRIPTION +.B pmdaInit +initializes a PMDA so that it is ready to receive PDUs from +.BR pmcd (1). +The function expects as arguments the instance domain table +.RI ( indoms ) +and the metric description table +.RI ( metrics ) +that are initialized by the PMDA. The arguments +.I nindoms +and +.I nmetrics +should be set to the number of instances and metrics in the tables, +respectively. +.PP +Much of the +.B +pmdaInterface +structure can be automatically initialized with +.BR pmdaDaemon (3), +.BR pmdaGetOpt (3) +and +.BR pmdaDSO (3). +.B pmdaInit +completes the PMDA initialization phase with three operations. +The first operation adds the domain and instance numbers to the instance and +metric tables. Singular metrics (metrics without an instance domain) should +have the instance domain +.B PM_INDOM_NULL +set in the +.I indom +field of the +.B pmDesc +structure (see +.BR pmLookupDesc (3)). +Metrics with an instance domain should set this field to be the serial number +of the instance domain in the +.I indoms +table. +.PP +The instance domain table may be made empty by setting +.I indoms +to NULL and +.I nindoms +to 0. +This allows the caller to provide custom Fetch and Instance callback functions. +The metric table may be made empty by setting +.I metrics +to NULL and +.I nmetrics +to 0. +This allows the caller to provide custom Fetch and Descriptor callback functions. +.SH EXAMPLE +For example, a PMDA has three metrics: A, B and C, and two instance +domains X and Y, with two instances in each instance domain. The instance +domain and metrics description tables could be defined as: +.PP +.nf +.ft CW +.in +0.5i +static pmdaInstid _X[] = { + { 0, "X1" }, { 1, "X2" } +}; + +static pmdaInstid _Y[] = { + { 0, "Y1" }, { 1, "Y2" } +}; + +static pmdaIndom indomtab[] = { +#define X_INDOM 0 + { X_INDOM, 2, _X }, +#define Y_INDOM 3 + { Y_INDOM, 2, _Y } +}; + +static pmdaMetric metrictab[] = { +/* A */ + { (void *)0, + { PMDA_PMID(0,0), PM_TYPE_U32, PM_INDOM_NULL, PM_SEM_INSTANT, + { 0,0,0,0,0,0} }, }, +/* B */ + { (void *)0, + { PMDA_PMID(0,1), PM_TYPE_U32, X_INDOM, PM_SEM_INSTANT, + { 0,0,0,0,0,0} }, }, +/* C */ + { (void *)0, + { PMDA_PMID(0,2), PM_TYPE_DOUBLE, Y_INDOM, PM_SEM_INSTANT, + { 0,1,0,0,PM_TIME_SEC,0} }, } +}; +.in +.fi +.PP +The metric description table defines metric A with no instance domain, +metric B with instance domain X and metric C with instance domain Y. Metric +C has units of seconds, while the other metrics have no units (simple counters). +.B pmdaInit +will take these structures and assign the +.BR PMDA (3) +domain number to the +.I it_indom +field of each instance domain. This identifier also replaces the +.I indom +field of all metrics which have that instance domain, so that they are +correctly associated. +.PP +The second stage opens the +help text file, if one was specified with the +.B \-h +command line option (see +.BR pmdaGetOpt (3)) +or as a +.I helptext +argument to +.BR pmdaDSO (3) +or +.BR pmdaDaemon (3). +.PP +The final stage involves preparing the metric table lookup strategy. +.SH "METRIC LOOKUP" +When fetch and descriptor requests are made of the PMDA, each +requested PMID must be mapped to a metric table entry. +There are currently three strategies for performing this mapping \- +direct, linear and hashed. +Each has its own set of tradeoffs and an appropriate strategy +should be selected for each PMDA. +.PP +If all of the metric PMID item numbers correspond to the position +in the +.I metrics +table, then direct mapping is used. +This is the most efficient of the lookup functions as it involves +a direct array index (no additional memory is required nor any +additional processing overhead). +If the PMID numbering requirement is met by the PMDA, it is ideal. +This strategy can be explicitly requested by calling +.BR pmdaSetFlags \c +(\f2pmda\f1, \f2PMDA_FLAG_EXT_DIRECT\f1) +before calling +.BR pmdaInit . +In this case, if the direct mapping is not possible (e.g. due to +an oversight on the part of the PMDA developer), a warning is +logged and the linear strategy is used instead. +.PP +The second strategy (linear search) is the default, when a direct +mapping cannot be established. +This provides greater flexibility in the PMID numbering scheme, +as the PMDA item numbers do not have to be unique (hence, the PMID +cluster numbers can be used more freely, which is often extremely +convenient for the PMDA developer). +However, lookup involves a linear walk from the start of the metric +table until a matching PMID is found, for each requested PMID in a +request. +.PP +The third strategy (hash lookup) can be requested by calling +.BR pmdaSetFlags \c +(\f2pmda\f1, \f2PMDA_FLAG_EXT_HASHED\f1) +before calling +.BR pmdaInit . +This strategy is most useful for PMDAs with large numbers of metrics +(many hundreds, or thousands). +Such PMDAs will almost always use the cluster numbering scheme, so +the direct lookup scheme becomes inappropriate. +They may also be prepared to sacrifice a small amount of additional +memory for a hash table, mapping PMID to metric table offsets, to +speed up lookups in their vast metric tables. +.PP +This final strategy can also be used by PMDAs serving up dynamically +numbered metrics. +For this case, the +.B pmdaRehash +function should be used to replace the metric table when new metrics +become available, or existing metrics are removed. +The PMID hash mapping will be recomputed at the same time that the +new metric table is installed. + +.SH DIAGNOSTICS +.B pmdaInit +will set +.I dispatch->status +to a value less than zero if there is an error that would prevent the +.BR PMDA (3) +from successfully running. +.BR pmcd (1) +will terminate the connection to the +.BR PMDA (3) +if this occurs. +.PP +.B pmdaInit +may issue any of these messages: +.TP 15 +.BI "PMDA interface version " interface " not supported" +The +.I interface +version is not supported by +.BR pmdaInit . +.TP +.B "Using pmdaFetch() but fetch call back not set" +The fetch callback, +.BR pmdaFetch (3), +requires an additional callback to be provided using +.BR pmdaSetFetchCallBack (3). +.TP +.BI "Illegal instance domain " inst " for metric " pmid +The instance domain +.I inst +that was specified for metric +.I pmid +is not within the range of the instance domain table. +.TP +.B No help text path specified +The help text callback, +.BR pmdaText (3), +requires a help text file for the metrics to have been opened, however +no path to the help text was specified as a command line option, or as an +argument to +.BR pmdaDSO (3) +or +.BR pmdaDaemon (3). +This message is only a warning. +.TP +.BI "Direct mapping for metrics disabled @ " num +The unit numbers of the metrics did not correspond to the index in the +metric description table. The direct mapping failed for metric number +.I num +in the +.I metrics +table. This is less efficient but is not fatal and the message is only a +warning. +.TP +.BI "Hashed mapping for metrics disabled @ " num +A memory allocation failure occurred while building the hash table to +index the metric description table. +This is a non-fatal warning message - a fallback to linear searching +will be automatically performed should this situation arise. +.SH CAVEAT +The PMDA must be using +.B PMDA_INTERFACE_2 +or later, as specified in the call to +.BR pmdaDSO (3) +or +.BR pmdaDaemon (3). +.SH SEE ALSO +.BR newhelp (1), +.BR pmcd (1), +.BR PMAPI (3), +.BR PMDA (3), +.BR pmdaDaemon (3), +.BR pmdaDSO (3), +.BR pmdaFetch (3), +.BR pmdaGetOpt (3), +.BR pmdaText (3) +and +.BR pmLookupDesc (3). diff --git a/man/man3/pmdainstance.3 b/man/man3/pmdainstance.3 new file mode 100644 index 0000000..8b7fd97 --- /dev/null +++ b/man/man3/pmdainstance.3 @@ -0,0 +1,148 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000-2004 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMDAINSTANCE 3 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmdaInstance\f1 \- return instance descriptions for a PMDA +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.br +#include <pcp/impl.h> +.br +#include <pcp/pmda.h> +.sp +.ad l +.hy 0 +.in +8n +.ti -8n +int pmdaInstance(pmInDom \fIindom\fP, int \fIinst\fP, char *\fIname\fP, __pmInResult\ **\fIresult\fP, pmdaExt\ *\fIpmda\fP); +.sp +.in +.hy +.ad +cc ... \-lpcp_pmda \-lpcp +.ft 1 +.SH DESCRIPTION +.B pmdaInstance +uses the standard +.BR PMDA (3) +data structures to return information concerning the instance domain +.IR indom . +.PP +The +.I result +structure is constructed by +.B pmdaInstance +and will contain one or more instance names and/or identifiers as specified by +the +.I inst +and +.I name +arguments. +.PP +If +.I inst +has the value +.B PM_IN_NULL +and +.I name +is a null string, +.I result +will contain all the instances names and identifiers in the instance domain. +.PP +If +.I inst +is +.B PM_IN_NULL +but +.I name +is the name of an instance in the instance domain +.IR indom , +then +.I result +will contain the instance identifier for instance +.IR name . +Note that if +.I name +contains no spaces, partial matching up to the first space in the +instance name is performed, i.e. +.RB `` 1 '' +will match instance name +.RB `` 1 +.BR minute ''. +If +.I name +contains an embedded space, then no partial matching is performed and +.I name +should match one of the instance names exactly. +.PP +If +.I name +is a null string but +.I inst +is an instance identifier in the instance domain +.IR indom , +then +.I result +will contain the name for instance +.IR inst . +The +.I result +structure is allocated with +.BR malloc (3) +and should be released by the caller with +.BR free (3). +.SH DIAGNOSTICS +If any errors occur during the execution of +.BR pmdaInstance , +the +.I result +structure is deallocated. If the instance domain +.I indom +is not supported by the PMDA, +.B pmdaInstance +will return +.BR PM_ERR_INDOM . +.PP +If the +.I inst +or +.I name +does not correspond to any instances in the +.I indom +domain, +.B pmdaInstance +will return +.BR PM_ERR_INST . +.SH CAVEAT +The PMDA must be using +.B PMDA_INTERFACE_2 +or later, as specified in the call to +.BR pmdaDSO (3) +or +.BR pmdaDaemon (3). +.PP +Because of optional partial matching up to the first space in the instance +name, the +.B PMDA +developer should ensure that if instance names are allowed to have +spaces, the names are unique up to the first space. +.SH SEE ALSO +.BR malloc (3), +.BR PMAPI (3), +.BR PMDA (3) +and +.BR pmGetInDom (3). diff --git a/man/man3/pmdamain.3 b/man/man3/pmdamain.3 new file mode 100644 index 0000000..41550a9 --- /dev/null +++ b/man/man3/pmdamain.3 @@ -0,0 +1,299 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2013 Red Hat. +.\" Copyright (c) 2000-2004 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMDAMAIN 3 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmdaMain\f1, +\f3pmdaGetContext\f1, +\f3pmdaSetResultCallBack\f1, +\f3pmdaSetCheckCallBack\f1, +\f3pmdaSetDoneCallBack\f1, +\f3pmdaSetEndContextCallBack\f1 \- generic PDU processing for a PMDA +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.br +#include <pcp/impl.h> +.br +#include <pcp/pmda.h> +.sp +cc ... \-lpcp_pmda \-lpcp +.sp +.ad l +.hy 0 +.in +8n +.ti -8n +void pmdaMain(pmdaInterface *\fIdispatch\fP); +.br +.ti -8n +void pmdaSetCheckCallBack(pmdaInterface *\fIdispatch\fP, pmdaCheckCallBack\ \fIcallback\fP); +.br +.ti -8n +void pmdaSetDoneCallBack(pmdaInterface *\fIdispatch\fP, pmdaDoneCallBack\ \fIcallback\fP); +.br +.ti -8n +void pmdaSetResultCallBack(pmdaInterface *\fIdispatch\fP, pmdaResultCallBack\ \fIcallback\fP); +.br +.ti -8n +void pmdaSetEndContextCallBack(pmdaInterface *\fIdispatch\fP, pmdaEndContextCallBack\ \fIcallback\fP); +.br +.ti -8n +int pmdaGetContext(void); +.sp +.in +.hy +.ad +.ft 1 +.SH DESCRIPTION +For Performance Metric Domain Agents +.RB ( PMDA (3)) +using the binary PDU protocols to communicate with +.BR pmcd (1), +the routine +.B pmdaMain +provides a generic implementation of the PDU-driven main loop. +.PP +.I dispatch +describes how to process each incoming PDU. It +is a vector of function pointers, one per request PDU type, +as used in the DSO interface for a PMDA, namely: +.PP +.nf +.ft CW +/* + * Interface Definitions for PMDA Methods + */ +typedef struct { + int domain; /* set/return performance metrics domain id here */ + struct { + unsigned int pmda_interface: 8; /* PMDA DSO interface 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 { + struct { /* PMDA_INTERFACE_2 or _3 */ + pmdaExt *ext; + int (*profile)(__pmProfile *, pmdaExt *); + int (*fetch)(int, pmID *, pmResult **, pmdaExt *); + int (*desc)(pmID, pmDesc *, pmdaExt *); + int (*instance)(pmInDom, int, char *, __pmInResult **, pmdaExt *); + int (*text)(int, int, char **, pmdaExt *); + int (*store)(pmResult *, pmdaExt *); + } two, three; + + struct { /* PMDA_INTERFACE_4 or _5 */ + pmdaExt *ext; + int (*profile)(__pmProfile *, pmdaExt *); + int (*fetch)(int, pmID *, pmResult **, pmdaExt *); + int (*desc)(pmID, pmDesc *, pmdaExt *); + int (*instance)(pmInDom, int, char *, __pmInResult **, pmdaExt *); + int (*text)(int, int, char **, pmdaExt *); + int (*store)(pmResult *, pmdaExt *); + int (*pmid)(char *, pmID *, pmdaExt *); + int (*name)(pmID, char ***, pmdaExt *); + int (*children)(char *, int, char ***, int **, pmdaExt *); + } four, five; + + struct { /* PMDA_INTERFACE_6 */ + pmdaExt *ext; + int (*profile)(__pmProfile *, pmdaExt *); + int (*fetch)(int, pmID *, pmResult **, pmdaExt *); + int (*desc)(pmID, pmDesc *, pmdaExt *); + int (*instance)(pmInDom, int, char *, __pmInResult **, pmdaExt *); + int (*text)(int, int, char **, pmdaExt *); + int (*store)(pmResult *, pmdaExt *); + int (*pmid)(char *, pmID *, pmdaExt *); + int (*name)(pmID, char ***, pmdaExt *); + int (*children)(char *, int, char ***, int **, pmdaExt *); + int (*attribute)(int, int, const char *, int, pmdaExt *); + } six; + } version; + +} pmdaInterface; +.fi +.PP +This structure has been extended to incorporate the multiple interface versions +that have evolved over time. +For +.BR pmdaMain, +.I dispatch->domain +and +.I dispatch->status +are ignored. The +.I comm.pmda_interface +field is used to determine the interface used by the PMDA. Setting this field +to +.B PMDA_INTERFACE_2 +or +.B PMDA_INTERFACE_3 +will force +.B pmdaMain +to use the callbacks in the +.I version.two +or +.I version.three +structure. +A setting of +.B PMDA_INTERFACE_4 +or +.B PMDA_INTERFACE_5 +will force +.B pmdaMain +to use the callbacks in the +.I version.four +or +.I version.five +structure, and similarly a +.B PMDA_INTERFACE_6 +setting forces +.B pmdaMain +to use the callbacks in the +.I version.six +structure. +Any other value will result in an error and termination of +.BR pmdaMain . +.PP +Note that the use of +.B dispatch +as the interface between the +.BR pmcd (1) +and the methods of the PMDA allows each PMDA to be implemented as +though it were a DSO, with +.B pmdaMain +providing a convenient wrapper that may be used to convert from the +DSO interface to the binary PDU (daemon PMDA) interface. +.PP +.B pmdaMain +executes as a continuous loop, returning only when an end of file +is encountered on the PDU input file descriptor. +.SH CALLBACKS +In addition to the individual PDU processing callbacks \- +.BR pmdaProfile (3), +.BR pmdaFetch (3), +.BR pmdaDesc (3), +.BR pmdaInstance (3), +.BR pmdaText (3), +.BR pmdaStore (3), +.BR pmdaPMID (3), +.BR pmdaName (3), +.BR pmdaChildren (3), +and +.BR pmdaAttribute (3) +there are other callbacks that can affect or inform all PDU +processing within a PMDA, namely +.IR check , +.I done +and +.IR end . +These callbacks should be set with +.BR pmdaSetCheckCallBack , +.B pmdaSetDoneCallBack +and +.BR pmdaSetEndContextCallBack . +.PP +If not null, +.I check +is called after each PDU is received (but before it was processed), and +.I done +is called after each PDU is sent. +If +.I check +returns a value less than zero (typically PM_ERR_AGAIN), +the PDU processing is skipped and in most cases the +function value is returned as an error PDU to +.BR pmcd (1) +\- this may be used for +PMDAs that require some sort of deferred connection or reconnect +protocols for the underlying sources of performance metrics, e.g. a DBMS. +The error indication from +.I check +is not passed back to +.BR pmcd (1) +in the cases where no acknowledgment is expected, e.g. for a PDU_PROFILE. +.PP +The +.I end +callback allows a PMDA to keep track of state for individual clients that +are requesting it to perform actions (PDU processing). +Using +.B pmdaGetContext +a PMDA can determine, at any point, an integer identifier that uniquely +identifies the client tools at the remote end of PMCD (for local context +modes, this identifier is always zero). +This becomes very important for handling event metrics, where each +event must be propogated once only to each interested client. +It also underlies the mechanism whereby connection information is passed +to the PMDA, such as the the credentials (user and group identifiers) for +the client tool. +.PP +One final callback mechanism is provided for handling the +.B pmResult +built for a PDU_RESULT in response to a PDU_FETCH request. +By default, +.B pmdaMain +will free the +.B pmResult +once the result has been sent to the +.BR pmcd (1). +For some PMDAs this is inappropriate, e.g. the +.B pmResult +is statically allocated, or contains a hybrid of pinned PDU buffer +information and dynamically allocated information. +.B pmdaSetResultCallback +may be used to define an alternative +.B callback +from +.BR pmdaMain . +.SH DIAGNOSTICS +These messages may be appended to the PMDA's log file: +.TP 25 +.BI "PMDA interface version " interface " not supported" +The +.I interface +version is not supported by +.BR pmdaMain . +.TP +.B Unrecognized pdu type +The PMDA received a PDU from +.B pmcd +that it does not recognize. This may indicate that the +.B pmcd +process is using a more advanced interface than +.BR pmdaMain . +.PP +If the +.BR PMAPI (3) +debug control variable +.RB ( pmdebug ) +has the DBG_TRACE_LIBPMDA flag set then each PDU that is received is reported +in the PMDA's log file. +.SH SEE ALSO +.BR pmcd (1), +.BR PMAPI (3), +.BR PMDA (3), +.BR pmdaProfile (3), +.BR pmdaFetch (3), +.BR pmdaDesc (3), +.BR pmdaInstance (3), +.BR pmdaText (3), +.BR pmdaStore (3), +.BR pmdaPMID (3), +.BR pmdaName (3), +.BR pmdaChildren (3), +and +.BR pmdaAttribute (3). diff --git a/man/man3/pmdaname.3 b/man/man3/pmdaname.3 new file mode 100644 index 0000000..2c81493 --- /dev/null +++ b/man/man3/pmdaname.3 @@ -0,0 +1,89 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000-2004 Silicon Graphics, Inc. All Rights Reserved. +.\" Copyright (c) 2009 Ken McDonell. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMDANAME 3 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmdaName\f1 \- translate a PMID to a set of dynamic performance metric names +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.br +#include <pcp/impl.h> +.br +#include <pcp/pmda.h> +.sp +int pmdaName(pmID \fIpmid\fP, char ***\fInameset\fP, pmdaExt *\fIpmda\fP); +.sp +cc ... \-lpcp_pmda \-lpcp +.ft 1 +.SH DESCRIPTION +As part of the Performance Metrics Domain Agent (PMDA) API (see +.BR PMDA (3)), +.BR pmdaName +is the generic callback for +translating a +.I pmid +into one or more dynamic metric names (\c +.IR nameset ). +.PP +Because implementing dynamic performance metrics requires specific +PMDA support, and the facility is an optional component of a PMDA (most +PMDAs do +.B not +support dynamic performance metrics), +.B pmdaName +is a skeleton implementation that returns +.BR PM_ERR_NAME . +.PP +A PMDA that supports dynamic performance metrics will provide a private +callback that replaces +.B pmdaName +(by assignment to +.I version.four.name +of the +.I pmdaInterface +structure) +and implements the translation from a +.I pmid +to a set of dynamic performance metric names returned via +.IR nameset . +The behaviour, return values and memory allocation rules for +.I nameset +are the same as for +.BR pmNameAll (3). +.SH DIAGNOSTICS +.B +pmdaName +returns +.B PM_ERR_PMID +if the name is not recognized or cannot be translated, +otherwise the number of metric names found (most commonly 1). +.SH CAVEAT +The PMDA must be using +.B PMDA_PROTOCOL_4 +or later, as specified in the call to +.BR pmdaDSO (3) +or +.BR pmdaDaemon (3). +.SH SEE ALSO +.BR PMAPI (3), +.BR PMDA (3), +.BR pmdaDaemon (3), +.BR pmdaDSO (3), +.BR pmdaMain (3), +.BR pmNameAll (3) +and +.BR pmNameID (3). diff --git a/man/man3/pmdaopenlog.3 b/man/man3/pmdaopenlog.3 new file mode 100644 index 0000000..22762c6 --- /dev/null +++ b/man/man3/pmdaopenlog.3 @@ -0,0 +1,78 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000-2004 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMDAOPENLOG 3 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmdaOpenLog\f1 \- redirect stderr to a logfile +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.br +#include <pcp/impl.h> +.br +#include <pcp/pmda.h> +.sp +void pmdaOpenLog(pmdaInterface * \fIdispatch\fP); +.sp +cc ... \-lpcp_pmda \-lpcp +.ft 1 +.SH DESCRIPTION +.B pmdaOpenLog +redirects +.I stderr +to the logfile specified in the +.I dispatch +structure, set by the previous call to +.BR pmdaDaemon (3) +or +.BR pmdaGetOpt (3). +The first line of the log file will detail the name of the calling process, +the host the process is running on, and the current time. In addition, the +log is appended with the exit time of the process by +a routine registered with +.BR atexit (3C). +.SH CAVEAT +The PMDA must be using +.B PMDA_PROTOCOL_2 +or later, as specified in the call to +.BR pmdaDSO (3) +or +.BR pmdaDaemon (3). +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.I /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). +Values for these variables may be obtained programmatically +using the +.IR pmGetConfig (3) +function. +.SH SEE ALSO +.BR pmcd (1), +.BR atexit (2), +.BR PMAPI (3), +.BR PMDA (3), +.BR pmdaDaemon (3) +and +.BR pmdaGetOpt (3). diff --git a/man/man3/pmdapmid.3 b/man/man3/pmdapmid.3 new file mode 100644 index 0000000..295d939 --- /dev/null +++ b/man/man3/pmdapmid.3 @@ -0,0 +1,81 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000-2004 Silicon Graphics, Inc. All Rights Reserved. +.\" Copyright (c) 2009 Ken McDonell. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMDAPMID 3 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmdaPMID\f1 \- translate a dynamic performance metric name into a PMID +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.br +#include <pcp/impl.h> +.br +#include <pcp/pmda.h> +.sp +int pmdaPMID(char *\fIname\fP, pmID *\fIpmid\fP, pmdaExt *\fIpmda\fP); +.sp +cc ... \-lpcp_pmda \-lpcp +.ft 1 +.SH DESCRIPTION +As part of the Performance Metrics Domain Agent (PMDA) API (see +.BR PMDA (3)), +.BR pmdaPMID +is the generic callback for translating a dynamic metric +.I name +into a PMID (\c +.IR pmid ). +.PP +Because implementing dynamic performance metrics requires specific +PMDA support, and the facility is an optional component of a PMDA (most +PMDAs do +.B not +support dynamic performance metrics), +.B pmdaPMID +is a skeleton implementation that returns +.BR PM_ERR_NAME . +.PP +A PMDA that supports dynamic performance metrics will provide a private +callback that replaces +.B pmdaPMID +(by assignment to +.I version.four.pmid +of the +.I pmdaInterface +structure) +and implements the translation from a dynamic performance metric +.I name +into the associated +.IR pmid . +.SH DIAGNOSTICS +.B pmdaPMID +returns +.B PM_ERR_NAME +if the name is not recognized or cannot be translated, else returns 0. +.SH CAVEAT +The PMDA must be using +.B PMDA_PROTOCOL_4 +or later, as specified in the call to +.BR pmdaDSO (3) +or +.BR pmdaDaemon (3). +.SH SEE ALSO +.BR PMAPI (3), +.BR PMDA (3), +.BR pmdaDaemon (3), +.BR pmdaDSO (3), +.BR pmdaMain (3) +and +.BR pmLookupName (3). diff --git a/man/man3/pmdaprofile.3 b/man/man3/pmdaprofile.3 new file mode 100644 index 0000000..0f64da3 --- /dev/null +++ b/man/man3/pmdaprofile.3 @@ -0,0 +1,59 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000-2004 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMDAPROFILE 3 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmdaProfile\f1 \- update instance profile for PMDA in preparation for the next fetch from PMCD +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.br +#include <pcp/impl.h> +.br +#include <pcp/pmda.h> +.sp +int pmdaProfile(__pmProfile *\fIprof\fP, pmdaExt *\fIpmda\fP); +.sp +cc ... \-lpcp_pmda \-lpcp +.ft 1 +.SH DESCRIPTION +As part of the Performance Metrics Domain Agent (PMDA) API (see +.BR PMDA (3)), +.B pmdaProfile +is the default callback which handles the receipt of a +.B __pmProfile +from +.BR pmcd (1). +A profile describes the instances that +.B pmcd +requires in the +.B pmResult +structure returned by the next fetch. +.B pmdaProfile +simply stores the new profile. +.SH CAVEAT +The PMDA must be using +.B PMDA_PROTOCOL_2 +or later, as specified in the call to +.BR pmdaDSO (3) +or +.BR pmdaDaemon (3). +.SH SEE ALSO +.BR PMAPI (3), +.BR PMDA (3), +.BR pmdaDaemon (3), +.BR pmdaDSO (3) +and +.BR pmdaFetch (3). diff --git a/man/man3/pmdastore.3 b/man/man3/pmdastore.3 new file mode 100644 index 0000000..dcf8840 --- /dev/null +++ b/man/man3/pmdastore.3 @@ -0,0 +1,62 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000-2004 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMDASTORE 3 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmdaStore\f1 \- store a value into a metric for a PMDA +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.br +#include <pcp/impl.h> +.br +#include <pcp/pmda.h> +.sp +int pmdaStore(pmResult *\fIresult\fP, pmdaExt *\fIpmda\fP); +.sp +cc ... \-lpcp_pmda \-lpcp +.ft 1 +.SH DESCRIPTION +As part of the Performance Metrics Domain Agent (PMDA) API (see +.BR PMDA (3)), +.BR pmdaStore +is the generic callback for storing a value into a metric. +.B pmdaStore +is usually a no-op as, by default, no metrics can be altered. +Also, the implementation of a store callback which does permit +metrics to be altered by +.BR pmstore (1) +is very application dependent. +.SH DIAGNOSTICS +.B +pmdaStore +returns +.B PM_ERR_PERMISSION +to indicate that no metrics may be modified. +.SH CAVEAT +The PMDA must be using +.B PMDA_PROTOCOL_2 +or later, as specified in the call to +.BR pmdaDSO (3) +or +.BR pmdaDaemon (3). +.SH SEE ALSO +.BR pmstore (1), +.BR PMAPI (3), +.BR PMDA (3), +.BR pmdaDaemon (3), +.BR pmdaDSO (3) +and +.BR pmStore (3). diff --git a/man/man3/pmdatext.3 b/man/man3/pmdatext.3 new file mode 100644 index 0000000..ef21e6a --- /dev/null +++ b/man/man3/pmdatext.3 @@ -0,0 +1,120 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000-2004 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMDATEXT 3 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmdaText\f1 \- extract metric help text for a PMDA +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.br +#include <pcp/impl.h> +.br +#include <pcp/pmda.h> +.sp +int pmdaText(int \fIident\fP, int \fItype\fP, char **\fIbuffer\fP, pmdaExt *\fIpmda\fP); +.sp +cc ... \-lpcp_pmda \-lpcp +.ft 1 +.SH DESCRIPTION +As part of the Performance Metrics Domain Agent (PMDA) API (see +.BR PMDA (3)), +.B pmdaText +uses the standard +.BR PMDA (3) +data structures to return the help text for metric +.I ident +in +.IR buffer . +The help text must be located in help text files +created with +.BR newhelp (1), +and the associated files are automatically opened by +.BR pmdaInit (3). +.PP +The path to the (basename of the) help text files can be set in the calls to +.BR pmdaDSO (3) +or +.BR pmdaDaemon (3) +and overridden by the +.B \-h +command line option in +.BR pmdaGetOpt (3). +.PP +The encoding of +.I ident +follows the internal scheme used below the routines +.BR pmLookupText (3) +and +.BR pmLookupInDomText (3), +namely +.I ident +encodes either a metric identifier or an instance domain +identifier, according to the value +of +.IR type . +.PP +The +.I type +argument is a bit mask that encodes the interpretation of +.I ident +and the requested form of help text, +as follows: +either +.B PM_TEXT_PMID +if +.I ident +is a metric identifier, or +.B PM_TEXT_INDOM +if +.I ident +is an instance domain identifier, plus +either +.B PM_TEXT_ONELINE +for the one line help text or +.B PM_TEXT_HELP +for the full help text. +.PP +The +.I buffer +is managed internally (usually it is cached), +and it should +.B not +be released or freed by the caller of +.BR pmdaText . +.SH DIAGNOSTICS +If the requested help text +could not be obtained, +.B pmdaText +will return +.BR PM_ERR_TEXT . +.SH CAVEAT +The PMDA must be using +.B PMDA_PROTOCOL_2 +or later, as specified in the call to +.BR pmdaDSO (3) +or +.BR pmdaDaemon (3). +.SH SEE ALSO +.BR newhelp (1), +.BR malloc (3), +.BR PMAPI (3), +.BR PMDA (3), +.BR pmdaDaemon (3), +.BR pmdaDSO (3), +.BR pmdaInit (3), +.BR pmLookupInDomText (3) +and +.BR pmLookupText (3). diff --git a/man/man3/pmdatrace.3 b/man/man3/pmdatrace.3 new file mode 100644 index 0000000..a9c1569 --- /dev/null +++ b/man/man3/pmdatrace.3 @@ -0,0 +1,341 @@ +'\"! tbl | mmdoc +'\"macro stdmacro +.\" +.\" Copyright (c) 2000-2004 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMDATRACE 3 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmtracebegin\f1, +\f3pmtraceend\f1, +\f3pmtraceabort\f1, +\f3pmtracepoint\f1, +\f3pmtraceobs\f1, +\f3pmtracecounter\f1, +\f3pmtracestate\f1, +\f3pmtraceerrstr\f1 \- application-level performance instrumentation services +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/trace.h> +.sp +.nf +int pmtracebegin(const char *\fItag\fP); +int pmtraceend(const char *\fItag\fP); +int pmtraceabort(const char *\fItag\fP); +int pmtracepoint(const char *\fItag\fP); +int pmtraceobs(const char *\fItag\fP, double \fIvalue\fP); +int pmtracecounter(const char *\fItag\fP, double \fIvalue\fP); +char *pmtraceerrstr(int \fIcode\fP); +int pmtracestate(int \fIflags\fP); +.fi +.sp +cc ... \-lpcp_trace +.ft 1 +.SH "FORTRAN SYNOPSIS" +.ft 3 +.nf +character*(*) \fItag\fP +integer \fIcode\fP +integer \fIflags\fP +integer \fIstate\fP +character*(*) \fIestr\fP +real*8 \fIvalue\fP +.fi +.sp +.nf +\fIcode\fP = pmtracebegin(\fItag\fP) +\fIcode\fP = pmtraceend(\fItag\fP) +\fIcode\fP = pmtraceabort(\fItag\fP) +\fIcode\fP = pmtracepoint(\fItag\fP) +\fIcode\fP = pmtraceobs(\fItag\fP, \fIvalue\fP) +\fIcode\fP = pmtracecounter(\fItag\fP, \fIvalue\fP) +pmtraceerrstr(\fIcode\fP, \fIestr\fP) +\fIstate\fP = pmtracestate(\fIflags\fP) +.fi +.sp +.nf +f77 ... \-lpcp_trace \f1or\f3 f90 ... \-lpcp_trace +.fi +.ft 1 +.SH "JAVA SYNOPSIS" +.ft 3 +.nf +.sp +import sgi.pcp.trace; +.sp +.nf +int trace.pmtracebegin(String \fItag\fP); +int trace.pmtraceend(String \fItag\fP); +int trace.pmtraceabort(String \fItag\fP); +int trace.pmtracepoint(String \fItag\fP); +int trace.pmtraceobs(String \fItag\fP, double \fIvalue\fP); +int trace.pmtracecounter(String \fItag\fP, double \fIvalue\fP); +String trace.pmtraceerrstr(int \fIcode\fP); +int trace.pmtracestate(int \fIflags\fP); +.fi +.sp +.ft 1 +.SH DESCRIPTION +.de CW +.ie t \f(CW\\$1\f1\\$2 +.el \fI\\$1\f1\\$2 +.. +The +.I pcp_trace +library functions provide a mechanism for identifying sections of a program +as transactions or events for use by the trace Performance Metrics Domain Agent +(refer to +.BR pmdatrace (1) +and +.BR PMDA (3)). +.PP +The monitoring of transactions using the Performance Co-Pilot (PCP) +infrastructure is initiated through a call to +.BR pmtracebegin . +Time will be recorded from the end of each +.B pmtracebegin +call to the start of the following call to +.BR pmtraceend , +where the same \f2tag\f1 identifier is used in both calls. +Following from this, no visible recording will occur until at least one call to +.B pmtraceend +is made referencing a \f2tag\f1 previously used in a call to +.BR pmtracebegin . +.PP +A transaction which is currently in progress can be cancelled by calling +.BR pmtraceabort . +No transaction data gathered for that particular transaction will be exported, +although data from previous and subsequent successful transactions with that +.I tag +name are still exported. This is most useful when an error condition +arises during transaction processing and the transaction does not run to +completion. +.PP +The \f2tag\f1 argument to +.BR pmtracebegin , +.B pmtraceend +and +.B pmtraceabort +is used to uniquely identify each transaction within the +.I pcp_trace +library and later by the trace PMDA as the instance domain identifiers for the +transaction performance metrics which it exports. +These routines are most useful when used around blocks of code which are +likely to be executed a number of times over some relatively long time +period (in a daemon process, for example). +.PP +.B pmtracebegin +has two distinct roles \- firstly as the initiator of a new transaction, +and secondly as a mechanism for setting a new start time. +Similarly, +.B pmtraceend +is used to register a new \f2tag\f1 and its initial state with the trace +PMDA, or alternatively to update the statistics which the PMDA currently +associates with the given \f2tag\f1. +.PP +A second form of program instrumentation can be obtained from +.BR pmtracepoint . +This is a simpler form of monitoring as it exports only the number of times +that a particular point in a program has been passed. This differs to the +transaction monitoring offered by +.B pmtracebegin +and +.BR pmtraceend , +which exports a running count of successful transaction completions as well as +statistics on the time interval between the start and end points of each +transaction. +This function is most useful when start and end points are not well defined. +Examples of this would be 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 the desired instrumentation is akin to event rates rather than event +service times. +.PP +The +.BR pmtraceobs +and +.BR pmtracecounter +functions have similar semantics to +.BR pmtracepoint , +but also allow an arbitrary numeric \f2value\f1 to be passed to the trace +PMDA. +The most recent \f2value\f1 for each \f2tag\f1 is then immediately available +from the PMDA. The only difference between +.BR pmtraceobs +and +.BR pmtracecounter +is that the value exported via +.BR pmtracecounter +is assumed to be a monotonically increasing counter value (e.g. the number +of bytes read from a socket), whereas the value exported via +.BR pmtraceobs +can be any value at all. +.PP +.B pmtracestate +allows the application to set state \f2flags\f1 which are honoured by +subsequent calls to the \f2pcp_trace\f1 library routines. +There are currently two types of flag \- debugging flags and the asynchronous +protocol flag. A single call may specify a number of \f2flags\f1 together, +combined using a (bitwise) logical OR operation, and overrides the previous +state setting. +.PP +The debugging flags to +.B pmtracestate +cause \f2pcp_trace\f1 to print diagnostic messages +on the standard output stream at important processing points. +The default protocol used between the trace PMDA and individual \f2pcp_trace\f1 +client applications is a synchronous protocol, which allows for dropped +connections to be reestablished at a later stage should this become possible. +An asynchronous protocol is also available which does not provide the +reconnection capability, but which does away with much of the overhead +inherent in synchronous communication. +This behaviour can be toggled using the +.B pmtracestate +call, but must be called before other calls to the library. This +differs to the debugging state behaviour, which can be altered at any time. +.B pmtracestate +returns the previous state (setting prior to being called). +.PP +The following table describes each of the +.B pmtracestate +\f2flags\f1 - examples of the use of these flags in each supported language are +given in the demo applications (refer to the ``FILES'' section below). +.TS +box,center; +cf(R) | cf(R) +lf(CW) | lf(R). +State Flags Semantics +_ +0 NONE Synchronous PDUs and no diagnostics (default) +1 API Shows processing just below the API (debug) +2 COMMS Shows network-related activity (debug) +4 PDU Shows app<->PMDA IPC traffic (debug) +8 PDUBUF Shows internal IPC buffer management (debug) +16 NOAGENT No PMDA communications at all (debug) +32 ASYNC Use the asynchronous PDU protocol (control) +.TE +.PP +Should any of the +.I pcp_trace +library functions return a negative value, +an error has occurred. This can be diagnosed further using the +.B pmtraceerrstr +routine, which takes the negative return value as its \f2code\f1 argument, +and in the C-callable interface returns a pointer to the associated error +message. +This points into a static error table, and should therefore not be passed to +.BR free (3). +The Fortran-callable interface has a slightly different syntax, requiring the +destination character array to be passed in as the second argument. +The Java-callable interface returns a UTF-8 string, created using the JNI +(Java Native Interface) routine +.BR NewStringUTF . +.SH ENVIRONMENT +The +.I pcp_trace +routines communicate with the trace PMDA via a socket connection, which by +default uses TCP/IP port number 4323. This can be over-ridden by setting +\f3PCP_TRACE_PORT\f1 to a different port number when the application is +started. The host where the trace PMDA is running is by default the +localhost, but this can be changed using \f3PCP_TRACE_HOST\f1. +When attempting to connect to a remote trace PMDA, after some specified time +interval has elapsed, the connection attempt will be aborted and an error +status will be returned. The default timeout interval is 3 seconds, and this +can be modified by setting \f3PCP_TRACE_TIMEOUT\f1 in the environment to a +real number of seconds for the desired timeout. 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. +.SH NOTES +The \f2pcp_trace\f1 Java class interface has been developed and verified using +version 1.1 of the Java Native Interface (JNI) specification. +.SH FILES +.TP 10 +.B $PCP_DEMOS_DIR/trace/*.c +Sample C programs and source for +.BR pmtrace (1). +Use +.BR make (1) +to build these programs. +.TP +.B $PCP_DEMOS_DIR/trace/fapp1.f +Sample Fortran program. +Call `make fortran77' or `make fortran90' to build this program. +.TP +.B $PCP_DEMOS_DIR/trace/japp1.java +Sample Java program. +`make java' builds the java class file. +.TP +.B /usr/java/classes/sgi/pcp/trace.java +Java trace class definition. +.PD +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.I /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). +Values for these variables may be obtained programmatically +using the +.IR pmGetConfig (3) +function. +.SH SEE ALSO +.B file:$PCP_DOC_DIR/Tutorial/trace.html, +.B pcp.man.tutorial, +Provided the, +.BR make (1), +.BR pmcd (1), +.BR pmdatrace (1), +.BR pmprobe (1), +.BR pmtrace (1), +Relevant information is also available from the on-line PCP Tutorial, +subsystem from the PCP images has been installed, access the URL +and +from your web browser. +.SH DIAGNOSTICS +A negative return value from a \f2pcp_trace\f1 function indicates that an +error has occurred \- if this is the case, the return value can be passed +to +.B pmtraceerrstr +to obtain the associated error message. +.PP +Success is indicated by a return value of zero. +.PP +.B pmtracestate +also returns an integer representing the state \f2flags\f1 which were set +prior to the call. +.SH CAVEAT +.P +Applications that use +.BR gethostbyname (3N) +should exercise caution because the static fields in +.I "struct hostent" +may not be preserved across some +.I pcp_trace +calls. +In particular, +.BR pmtracebegin , +.BR pmtraceend , +.BR pmtracepoint , +.BR pmtracecounter , +and +.B pmtraceobs +may all call +.BR gethostbyname (3N) +internally. diff --git a/man/man3/pmdelprofile.3 b/man/man3/pmdelprofile.3 new file mode 100644 index 0000000..09cd0d2 --- /dev/null +++ b/man/man3/pmdelprofile.3 @@ -0,0 +1,110 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000-2004 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMDELPROFILE 3 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmDelProfile\f1 \- delete instance(s) from the current PMAPI instance profile +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.sp +int pmDelProfile(pmInDom \fIindom\fP, int \fInuminst\fP, int *\fIinstlist\fP); +.sp +cc ... \-lpcp +.ft 1 +.SH DESCRIPTION +.de CW +.ie t \f(CW\\$1\f1\\$2 +.el \fI\\$1\f1\\$2 +.. +The set of instances for performance metrics returned from a +.BR pmFetch (3) +call may be filtered or restricted using an instance profile. +There is one instance profile for each context the application +creates at the Performance Metrics Application Programming Interface (PMAPI), +and each instance profile may include instances from one or more +instance domains (see +.BR pmLookupDesc (3)). +.PP +.B pmDelProfile +may be used to +delete instance specifications from the instance profile of the current +PMAPI context. +.PP +In the simplest variant, the list of instances identified by the +.I instlist +argument for the +.I indom +instance domain are removed from the instance +profile. +The list of instance identifiers contains +.I numinst +values. +.PP +The +.I indom +value would normally be extracted from a call to +.BR pmLookupDesc (3) +for a particular performance metric, and the instances in +.I instlist +would typically be determined by calls to +.BR pmGetInDom (3) +or +.BR pmLookupInDom (3). +.PP +If +.I indom +equals +.B PM_INDOM_NULL +or +.I numinst +is zero, +then all instance domains are selected for deletion. If +.I instlist +is +.CW "NULL" , +then all instances in the selected domain(s) are removed +from the profile. +.PP +To disable all available instances in all domains, use +.CW "pmDelProfile(PM_INDOM_NULL, 0, NULL)" . +This is the only situation in which +.I indom +may be +.BR PM_INDOM_NULL . +.SH SEE ALSO +.BR pmAddProfile (3), +.BR PMAPI (3), +.BR pmFetch (3), +.BR pmGetInDom (3), +.BR pmLookupDesc (3), +.BR pmLookupInDom (3), +.BR pmNewContext (3), +.BR pmUseContext (3) +and +.BR pmWhichContext (3). +.SH DIAGNOSTICS +.IP \f3PM_ERR_PROFILESPEC\f1 +.I indom +was +.B PM_INDOM_NULL +and +.I instlist +was not empty +.SH CAVEAT +It is possible to delete non-existent instance domains and non-existent +instances from an instance profile. None of the routines that use the instance +profile will ever issue an error if you do this. The cost of checking, when +checking is possible, outweighs any benefits. diff --git a/man/man3/pmderivederrstr.3 b/man/man3/pmderivederrstr.3 new file mode 100644 index 0000000..e8c2789 --- /dev/null +++ b/man/man3/pmderivederrstr.3 @@ -0,0 +1,38 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2009 Ken McDonell. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMDERIVEDERRSTR 3 "" "Performance Co-Pilot" +.SH NAME +\f3pmDerivedErrStr\f1 \- return error message from failure to parse derived metric definition +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.sp +char *pmDerivedErrStr(void); +.sp +cc ... \-lpcp +.ft 1 +.SH DESCRIPTION +.PP +When +.BR pmRegisterDerived (3) +is called to add a new derived metric definition and an error occurs, +.B pmDerivedErrStr +may be called to return the associated error message. +.SH SEE ALSO +.BR PCPIntro (1), +.BR PMAPI (3) +and +.BR pmRegisterDerived (3). diff --git a/man/man3/pmdestroycontext.3 b/man/man3/pmdestroycontext.3 new file mode 100644 index 0000000..72d41ea --- /dev/null +++ b/man/man3/pmdestroycontext.3 @@ -0,0 +1,79 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000-2004 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMDESTROYCONTEXT 3 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmDestroyContext\f1 \- destroy a PMAPI context +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.sp +int pmDestroyContext(int \fIhandle\fP); +.sp +cc ... \-lpcp +.ft 1 +.SH DESCRIPTION +.de CW +.ie t \f(CW\\$1\f1\\$2 +.el \fI\\$1\f1\\$2 +.. +An application using the +Performance Metrics Application Programming Interface (PMAPI) +may manipulate several concurrent contexts, +each associated with a source of performance metrics, e.g. \c +.BR pmcd (1) +on some host, or an archive log of performance metrics as created by +.BR pmlogger (1). +.PP +.B pmDestroyContext +destroys the PMAPI context identified by +.IR handle . +Typically this would imply some termination of a connection +to a PMCD or closing an archive log file, and orderly clean-up. +.PP +The context +must have been previously created using +.BR pmNewContext (3) +or +.BR pmDupContext (3). +.PP +On success, +.B pmDestroyContext +returns zero. +If +.I handle +was the current +PMAPI context, then the current context becomes undefined. +This means the application must explicitly re-establish a valid +PMAPI context with +.BR pmUseContext (3), +or create a new context with +.BR pmNewContext (3) +or +.BR pmDupContext (3), +before the next PMAPI operation that requires a PMAPI context. +.SH SEE ALSO +.BR PMAPI (3), +.BR pmDupContext (3), +.BR pmNewContext (3), +.BR pmUseContext (3) +and +.BR pmWhichContext (3). +.SH DIAGNOSTICS +.P +.B PM_ERR_NOCONTEXT +.IP +.I handle +does not identify a valid PMAPI context diff --git a/man/man3/pmdiscoverservices.3 b/man/man3/pmdiscoverservices.3 new file mode 100644 index 0000000..cfe7a77 --- /dev/null +++ b/man/man3/pmdiscoverservices.3 @@ -0,0 +1,154 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2014 Red Hat. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMDISCOVERSERVICES 3 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmDiscoverServices\f1 \- discover PCP services on the network +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.sp +.nf +int pmDiscoverServices(const char *\fIservice\fP, const char *\fImechanism\fP, const char *\fIglobalOptions\fP, char ***\fIurls\fP); +.fi +.sp +cc ... \-lpcp +.ft 1 +.SH DESCRIPTION +.de CW +.ie t \f(CW\\$1\f1\\$2 +.el \fI\\$1\f1\\$2 +.. +Given a PCP service name, as identified by +.IR service , +and using the type of discovery optionally specified in +.IR mechanism , +.B pmDiscoverServices +returns, via +.IR urls , +a list of URLs representing the services discovered on the network. +.PP +.I service +specifies the PCP service to be discovered. Currently supported services are +.B PM_SERVER_SERVICE_SPEC, +.B PM_PROXY_SERVICE_SPEC +and +.B PM_WEBD_SERVICE_SPEC, +which search for +.BR pmcd (1), +.BR pmproxy (1), +and +.BR pmwebd (1), +servers respectively. +.PP +.IR mechanism +specifies the style of discovery to be used. +.PP +The currently supported mechanisms are: +.TP +.B avahi +This searches for services which are broadcasting using mDNS via +.BR avahi-daemon (8). +An optional suffix \fB",timeout=NNNN"\fP may be added +to specify the discovery timeout, in floating-point multiples of one +second. The default timeout is 0.5 seconds, which may be overridden +by the \fBAVAHI_DISCOVERY_TIMEOUT\fP environment variable, also +specified in floating-point multiples of one second. +.TP +.B probe=<net-address>/<mask-bits> +Actively probes the given subnet for the requested PCP service(s). +<net-address> is an inet or ipv6 +network address and <mask-bits> is the number of bits used to define the +subnet. For example, 192.168.1.0/24 defines an 8 bit subnet consisting of the +addresses 192.168.1.0 through 192.168.1.255. +An optional suffix \fB",maxThreads=N"\fP may be added to limit the number of +threads used while probing. The default is no fixed limit, which is to say that +the process' rlimits for the number of threads and open file descriptors +will be respected. +.PP +.IR mechanism +may also be NULL, which means to use all available discovery mechanisms. +.PP +.I globalOptions +is a string containing options to be applied to the entire +discovery process. Currently, the only supported option is \fB"resolve"\fP. +Normally the +results are reported as a list of urls containing the network addresses +of the discovered servers. The \fB"resolve"\fP option requests +that an attempt be made to resolve these addresses. If successful, the host +name will be reported instead. If unsuccessful, then the address will be +reported. +.PP +.B pmDiscoverServices +will return the number of services discovered, else a value +less than zero for an error. +The value zero indicates that no services were discovered. +.PP +The resulting list of pointers, +.IR urls , +.B and +the values +(the URLs) that the pointers reference will have been +allocated by +.B pmDiscoverServices +with a single call to +.BR malloc (3C), +and it is the +responsibility of the +.B pmDiscoverServices +caller to +.BR free (\c +.IR urls ) +to release the space +when it is no longer required. +.PP +When an error occurs, or no services are discovered, +.I urls +is undefined (no space will have been +allocated, and so calling +.BR free (3C) +is a singularly bad idea). +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.I /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). +Values for these variables may be obtained programmatically +using the +.BR pmGetConfig (3) +function. +.SH SEE ALSO +.BR PMAPI (3), +.BR pmcd (1), +.BR pmproxy (1), +.BR pmwebd (1), +.BR pmfind (1), +.BR pmGetConfig (3), +.BR pcp.conf (5), +.BR pcp.env (5) +and +.BR avahi-daemon (8). +.SH DIAGNOSTICS +.IP \f3EOPNOTSUPP\f1 +The specified \fImechanism\fP is not supported. diff --git a/man/man3/pmdupcontext.3 b/man/man3/pmdupcontext.3 new file mode 100644 index 0000000..e106aa4 --- /dev/null +++ b/man/man3/pmdupcontext.3 @@ -0,0 +1,54 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000-2004 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMDUPCONTEXT 3 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmDupContext\f1 \- duplicate a PMAPI context +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.sp +int pmDupContext(void); +.sp +cc ... \-lpcp +.ft 1 +.SH DESCRIPTION +An application using the +Performance Metrics Application Programming Interface (PMAPI) +may manipulate several concurrent contexts, +each associated with a source of performance metrics, e.g. \c +.BR pmcd (1) +on some host, or an archive log of performance metrics as created by +.BR pmlogger (1). +.PP +Calling +.B pmDupContext +will +replicate the current PMAPI context, +returning a handle for the new context that may be used with subsequent +calls to +.BR pmUseContext (3). +.PP +Once created, the duplicated context and the original context have independent +existence, and so their instance profiles and +collection time (relevant only for archive contexts) +may be independently varied. +.PP +The newly replicated context becomes the current context. +.SH SEE ALSO +.BR PMAPI (3), +.BR pmNewContext (3) +and +.BR pmUseContext (3). diff --git a/man/man3/pmerrstr.3 b/man/man3/pmerrstr.3 new file mode 100644 index 0000000..3b26dc2 --- /dev/null +++ b/man/man3/pmerrstr.3 @@ -0,0 +1,69 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000-2004 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMERRSTR 3 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmErrStr\f1, +\f3pmErrStr_r\f1 \- convert a PMAPI error code into a string +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.sp +const char *pmErrStr(int \fIcode\fP); +.br +char *pmErrStr_r(int \fIcode\fP, char *\fIbuf\fP, int \fIbuflen\fP); +.sp +cc ... \-lpcp +.ft 1 +.SH DESCRIPTION +Translate an error code into a text string, suitable for generating a +diagnostic message. +The +.B pmErrStr_r +function does the same, but stores the result in a user-supplied buffer +.I buf +of length +.IR buflen , +which should have room for at least +.B PM_MAXERRMSGLEN +bytes. +.PP +By convention, all error codes are negative. +The small +values are assumed to be negated versions of the Unix error codes as defined +in +.B <errno.h> +and the strings returned are as per +.BR strerror (3C). +The larger, negative error codes are +Performance Metrics Application Programming Interface (PMAPI) +error conditions and +.BR pmErrStr (3) +returns an appropriate PMAPI error string, as determined by +.IR code . +.SH NOTES +.B pmErrStr +returns a pointer to a static buffer, +so the returned value is only valid until the next call to +.B pmErrStr +and hence is not thread-safe. +Multi-threaded applications should use +.B pmErrStr_r +instead. +.SH SEE ALSO +.BR pmerr (1), +.BR PMAPI (3) +and +.BR perror (3C). diff --git a/man/man3/pmeventflagsstr.3 b/man/man3/pmeventflagsstr.3 new file mode 100644 index 0000000..08b2077 --- /dev/null +++ b/man/man3/pmeventflagsstr.3 @@ -0,0 +1,68 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2010 Ken McDonell. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMEVENTFLAGSSTR 3 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmEventFlagsStr\f1, +\f3pmEventFlagsStr_r\f1 \- convert an event record flags value into a string +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.sp +const char *pmEventFlagsStr(int \fIflags\fP); +.br +char *pmEventFlagsStr_r(int \fIflags\fP, char *\fIbuf\fP, int \fIbuflen\fP); +.sp +cc ... \-lpcp +.ft 1 +.SH DESCRIPTION +.de CW +.ie t \f(CW\\$1\f1\\$2 +.el \fI\\$1\f1\\$2 +.. +For use in error and diagnostic messages, +.B pmEventFlagsStr +returns a `human readable' version of +the value +.IR flags , +assuming this to be the +.B er_flags +field of a +.B pmEventRecord +or +.BR pmEventHighResRecord . +The +.B pmEventFlagsStr_r +function does the same, but stores the result in a user-supplied buffer +.I buf +of length +.IR buflen , +which should have room for at least 64 bytes. +.PP +The string value result from +.B pmEventFlagsStr +is held in a single static buffer, so the returned value is +only valid until the next call to +.BR pmEventFlagsStr . +.SH NOTES +.B pmEventFlagsStr +returns a pointer to a static buffer and hence is not thread-safe. +Multi-threaded applications should use +.B pmEventFlagsStr_r +instead. +.SH SEE ALSO +.BR PMAPI (3) +and +.BR pmdaEventAddRecord (3). diff --git a/man/man3/pmextractvalue.3 b/man/man3/pmextractvalue.3 new file mode 100644 index 0000000..4f7266c --- /dev/null +++ b/man/man3/pmextractvalue.3 @@ -0,0 +1,255 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000-2004 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMEXTRACTVALUE 3 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmExtractValue\f1 \- extract a performance metric value from a pmResult structure +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.sp +.ad l +.hy 0 +.in +8n +.ti -8n +int pmExtractValue(int \fIvalfmt\fP, const pmValue *\fIival\fP, int\ \fIitype\fP, pmAtomValue\ *\fIoval\fP, int\ \fIotype\fP); +.sp +.in +.hy +.ad +cc ... \-lpcp +.ft 1 +.SH DESCRIPTION +.de CW +.ie t \f(CW\\$1\f1\\$2 +.el \fI\\$1\f1\\$2 +.. +The +.CW pmValue +structure is embedded within the +.CW pmResult +structure that is used to return one or more performance metrics; +see +.BR pmFetch (3). +.PP +All performance metric values may be encoded in a +.CW pmAtomValue +union, defined as follows; +.PP +.ft CW +.nf +.in +0.5i +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 */ + pmValueBlock *vbp; /* pmValueBlock ptr */ +} pmAtomValue; +.in +.fi +.ft 1 +.PP +The routine +.B pmExtractValue +provides a convenient mechanism for extracting values from the +.CW pmValue +part of a +.CW pmResult +structure, optionally converting the data type, and making the result +available to the application programmer. +.PP +.I itype +defines the data type of the input value held in +.I ival +according to the storage format defined by +.I valfmt +(see +.BR pmFetch (3)). +.I otype +defines the data type of the result to be placed in +.IR oval . +.PP +The value for +.I itype +is typically extracted from a +.CW pmDesc +structure, following a call to +.BR pmLookupDesc (3) +for a particular performance metric. +.PP +The +.I otype +value should be one of the defined +.BR PM_TYPE_ ... +values, that have a +1:1 correspondence with the fields in the +.CW pmAtomValue +union. +.PP +Normally the +.I valfmt +parameter would be plucked from the same +.CW pmResult +structure that provides the +.I ival +parameter, and if +.I valfmt +specifies +.BR PM_VAL_INSITU , +then the +following types are not allowed, as these cannot be encoded in 32-bits; +.BR __int64_t , +.BR __uint64_t , +.BR double , +.B char * +and +.B void * +(the corresponding +.I itype +values are +.BR PM_TYPE_64 , +.BR PM_TYPE_U64 , +.BR PM_TYPE_DOUBLE , +.BR PM_TYPE_STRING , +.B PM_TYPE_AGGREGATE +and +.B PM_TYPE_EVENT +respectively). +If +.I valfmt +specifies +.BR PM_VAL_PTR , +then the value will be extracted from the associated +.CW pmValueBlock +structure, and the +.BR __int32_t , +.B __uint32_t +and +.B float +options (\c +.I itype +being +.BR PM_TYPE_32 , +.B PM_TYPE_U32 +and +.B PM_TYPE_FLOAT +respectively) are not allowed, as +.B PM_VAL_INSITU +is the appropriate encoding for these. +.PP +The following table defines the various possibilities for the type +conversion -- the input type (\c +.IR itype ) +is shown vertically, and the output type (\c +.IR otype ) +is shown horizontally. +Y means the conversion is always acceptable, N means the conversion can never be performed (the function returns +.BR PM_ERR_CONV ), +P means the conversion may lose accuracy (but no error status is returned), +T means the result may be subject to high-order truncation (in which case +the function returns +.BR PM_ERR_TRUNC ) +and S means the conversion may be impossible due to the +sign of the input value (in which case the function returns +.BR PM_ERR_SIGN ). +If an error occurs, the value represented by +.I oval +will be zero (or +.BR NULL ). +.PP +Note that although some of the conversions involving the types +.B PM_TYPE_STRING +and +.B PM_TYPE_AGGREGATE +are indeed possible, but are marked N \- the rationale +is that +.B pmExtractValue +should not be attempting to duplicate functionality +already available in the C library via +.BR sscanf (3) +and +.BR sprintf (3). +.PP +No conversion involving the type +.B PM_TYPE_EVENT +is supported. +.PP +.ft CW +.nf + | 32 | U32 | 64 | U64 | FLOAT | DBLE | STRNG | AGGR | EVENT +======|=====|=======|=====|=======|=======|======|=======|======|======= +32 | Y | S | Y | S | P | P | N | N | N +U32 | T | Y | Y | Y | P | P | N | N | N +64 | T | T,S | Y | S | P | P | N | N | N +U64 | T | T | T | Y | P | P | N | N | N +FLOAT | P,T | P,T,S | P,T | P,T,S | Y | Y | N | N | N +DBLE | P,T | P,T,S | P,T | P,T,S | P | Y | N | N | N +STRNG | N | N | N | N | N | N | Y | N | N +AGGR | N | N | N | N | N | N | N | Y | N +EVENT | N | N | N | N | N | N | N | N | N +.fi +.ft 1 +.PP +In the cases where multiple conversion errors could occur, the first +encountered error will be notified, and the order of checking is not defined. +.PP +If the output conversion is to one of the pointer types, i.e. \c +.I otype +is +.B PM_TYPE_STRING +or +.BR PM_TYPE_AGGREGATE , +then the value buffer will have been allocated by +.BR pmExtractValue (3) +using +.BR malloc (3C), +and it is the caller's responsibility to free the space when it is no longer +required. +.PP +Although this function appears rather complex, it has been constructed to +assist the development of performance tools that wish to convert values, +whose type is only known via the +.CW type +field in a +.CW pmDesc +structure, into a canonical type for local processing. +.SH SEE ALSO +.BR PMAPI (3), +.BR pmAtomStr (3), +.BR pmConvScale (3), +.BR pmFetch (3), +.BR pmLookupDesc (3), +.BR pmPrintValue (3), +.BR pmTypeStr (3), +.BR pmUnitsStr (3) +and +.BR pmUnpackEventRecords (3). +.SH DIAGNOSTICS +.P +.B PM_ERR_CONV +.IP +Impossible conversion, marked by N in above table +.P +.B PM_ERR_TRUNC +.IP +High-order truncation occurred +.P +.B PM_ERR_SIGN +.IP +Conversion of negative value to unsigned type attempted diff --git a/man/man3/pmfetch.3 b/man/man3/pmfetch.3 new file mode 100644 index 0000000..893c59f --- /dev/null +++ b/man/man3/pmfetch.3 @@ -0,0 +1,376 @@ +'\"! tbl | mmdoc +'\"macro stdmacro +.\" +.\" Copyright (c) 2000-2004 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMFETCH 3 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmFetch\f1 \- get performance metric values +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.sp +.nf +int pmFetch(int \fInumpmid\fP, pmID *\fIpmidlist\fP, pmResult **\fIresult\fP); +.fi +.sp +cc ... \-lpcp +.ft 1 +.SH DESCRIPTION +.de CW +.ie t \f(CW\\$1\fR\\$2 +.el \fI\\$1\fR\\$2 +.. +.\" some useful acronyms ... always cite the full text at the first use +.\" and use uppercase acronym thereafter +.\" Performance Metrics Application Programming Interface (PMAPI) +.\" Performance Metrics Name Space (PMNS) +.\" Performance Metrics Collector Daemon (PMCD) +.\" Performance Metric ID (PMID) +Given a list of Performance Metric IDs (PMID)s, +e.g. as constructed by +.BR pmLookupName (3), +via +.I pmidlist +and +.IR numpmid , +fetch the values for these performance metrics. +.PP +The call to +.B pmFetch +is executed in the context of a source of metrics, +instance profile and collection time, +previously established by calls to +the appropriate context and profile functions, namely some of +.BR pmNewContext (3), +.BR pmDupContext (3), +.BR pmUseContext (3), +.BR pmAddProfile (3), +.BR pmDelProfile (3) +and +.BR pmSetMode (3). +.PP +The principal result from +.B pmFetch +is returned in the +argument +.I result +as a tree, using the following component data structures; +.PP +.ft CW +.nf +.in +0.5i +typedef struct { + unsigned int vtype : 8; /* value type (same as pmDesc.type) */ + unsigned int vlen : 24; /* bytes for vtype/vlen + vbuf */ + char vbuf[1]; /* one or more values */ +} pmValueBlock; + +typedef struct { + int inst; /* instance identifier */ + union { + pmValueBlock *pval; /* pointer to value-block */ + int lval; /* integer value insitu */ + } value; +} pmValue; + +typedef struct { + pmID pmid; /* metric identifier */ + int numval; /* number of values or error code */ + int valfmt; /* value style, insitu or ptr */ + pmValue vlist[1]; /* set of instances/values */ +} pmValueSet; + +/* Result returned by pmFetch() */ +typedef struct { + struct timeval timestamp; /* time stamped by collector */ + int numpmid; /* number of PMIDs */ + pmValueSet *vset[1]; /* set of value sets */ +} pmResult; +.in +.fi +.ft 1 +.PP +To accommodate metrics with multiple value instances, the +.CW numval +field indicates how many values are returned for each requested PMID. +The field +.CW valfmt +in the +.CW pmValueSet +structure indicates if the values for this metric are stored +.I insitu +in the +.CW lval +field, i.e. a 32-bit integer quantity (either int, unsigned int, +long or unsigned long) or if the values are held in associated +.CW pmValueBlock +structures. +The +.CW pmValueBlock +structure is always used for floating point values (float or double) +and also accommodates arbitrary sized binary data such as +`string-valued' metrics and metrics with aggregated or complex data types. +The maximum length of a +.CW pmValueBlock +buffer is +.B PM_VAL_VLEN_MAX +bytes. +If the +.CW pmValueBlock +format is used, the +.CW vtype +field indicates the data type of the value. +This field has the same interpretation as the +.CW type +field in the +.B pmDesc +structure, +see +.BR pmLookupDesc (3). +.PP +Note that the insitu value may be a signed or unsigned 32 bit integer, +signed or unsigned 32 bit long value (on 32 bit platforms), +In the special cases described below, it may also be a 32 bit floating +point value. +If the application needs to know the type of an insitu value, +which is almost always the case, it is necessary to +fetch the descriptor for the metric +and interpret the +.B type +field, as described in detail in +.BR pmLookupDesc (3). +When the +.CW pmResult +is received from a PCP1.x +.BR pmcd , +insitu values may also be 32 bit floating point values +(of type +.BR PM_TYPE_FLOAT ). +In all cases, it is good practice to use +.BR pmLookupDesc (3) +to fetch the descriptor for the metric and interpret the +.B type +field therein. +Note also that the +.BR PMAPI (3) +will automatically translate from the PCP2.0 format +to the PCP1.x format when a PCP1.x client requests 32 bit floating point values +from a PCP2.0 +.BR pmcd , +but the reverse translation does not occur (because the PCP2.0 +.B pmcd +cannot automatically distinguish between arbitrary 32 bit floating point values +and 32 bit integers). +.PP +If one value (i.e. associated with a particular instance) +for a requested metric is `unavailable' (at the requested time), +then there is no associated +.CW pmValue +structure in the +.IR result . +If there are no available values for a metric, +then +.CW numval +will be zero and the associated +.CW pmValue[] +instance will be empty (\c +.CW valfmt +is undefined in these circumstances, +however +.CW pmid +will be correctly set to the PMID of the metric with no values). +.PP +As an extension of this protocol, +if the Performance Metrics Collection System (PMCS) +is able to provide a reason why no values are available +for a particular metric, +this is encoded as a standard error code in the corresponding +.CW numval . +Since the error codes are all negative, +values for a requested metric are `unavailable' if +.CW numval +is less than, or equal to, zero. +A performance metric's value may be `unavailable' +for any of the following reasons; +.IP "+" 3n +The metric is not supported in this version +of the software for the associated Performance Metric Domain +.IP "+" +Collection is not currently activated +in the software for the associated Performance Metric Domain +.IP "+" +The associated PMID is not known +.IP "+" +The current system configuration does not include +the associated hardware component and/or the associated software module, +e.g. a disk is not installed, or off-line, or Oracle is not installed +.IP "+" +The metric is one for which an instance profile is required, +and none was provided (there are a small number of metrics in this category, +typically ones with very large, and/or very +dynamic instance domains, and/or expensive metric instantiation methods). +.PP +In general, we may not be able to differentiate between the various cases, +and if differentiation is not possible, +.CW numval +will simply be zero. +.PP +The argument definition and the result specifications have been constructed +to ensure that for each PMID in the requested +.I pmidlist +there is exactly one +.CW pmValueSet +in the +.IR result , +and further the PMIDs appear in exactly the same sequence in both +.I pmidlist +and +.IR result . +This makes the number +and order of entries in +.I result +completely deterministic, +and greatly simplifies the application programming logic +after the call to +.BR pmFetch . +.PP +The +.I result +structure returned by +.B pmFetch +is dynamically allocated using +a combination of +.BR malloc (3C) +calls +and specialized allocation strategies, +and should be released when no longer required by calling +.BR pmFreeResult (3) +\- under no circumstances should +.BR free (3C) +be called directly to release this space. +.PP +As common error conditions are encoded +in the +.I result +data structure, we'd expect only cataclysmic events +to cause an error value to be returned. +One example would be if the metrics source context was a remote host, +and that host or the PMCS on that host became unreachable. +Otherwise the value returned by the +.B pmFetch +function will be non-negative. +.PP +If the current context involves fetching metrics from a +Performance Metrics Collector Daemon (PMCD), then the return value +may be used to encode out-of-band changes in the state of the +PMCD and the associated +Performance Metrics Daemon Agents (PMDAs), as a bit-wise ``or'' of the +following values: +.sp 0.5v +.IP \fBPMCD_RESTART_AGENT\fR 20n +An attempt has been made to restart at least one failed PMDA. +.IP \fBPMCD_ADD_AGENT\fR +At least one PMDA has been started. +.IP \fBPMCD_DROP_AGENT\fR +PMCD has noticed the termination of at least one PMDA. +.PP +The default is to return zero to indicate +no change in state, however +the +.CW pmResult +returned by +.B pmFetch +has the same interpretation independent of the return value being +zero or greater than zero. +.SH SEE ALSO +.BR pmcd (1), +.BR pmAddProfile (3), +.BR PMAPI (3), +.BR pmDelProfile (3), +.BR pmDupContext (3), +.BR pmExtractValue (3), +.BR pmFetchArchive (3), +.BR pmFreeResult (3), +.BR pmGetInDom (3), +.BR pmLookupDesc (3), +.BR pmLookupName (3), +.BR pmNewContext (3), +.BR pmSetMode (3), +.BR pmUseContext (3) +and +.BR pmWhichContext (3). +.PP +Note that +.B pmFetch +is the most primitive method of fetching metric values from the PMCS. +More user friendly interfaces to the PMCS are available or currently +under development \- these higher level fetch methods insulate +the user from the intricacies of context creation, +setting up instance profiles, +.CW pmResult +traversal, and splitting fetches into batches to minimize PDU traffic +or according to other optimization criteria. +.SH DIAGNOSTICS +As mentioned above, +.B pmFetch +returns error codes +.I insitu +in the argument +.IR result . +If no result is returned, +e.g. due to IPC failure using the current PMAPI context, or +end of file on an archive log, +then +.B pmFetch +will return a negative error code which may be examined using +.BR pmErrStr (3). +.IP \f3PM_ERR_EOL\f1 +When fetching records from an archive log, +.B pmFetch +returns this error code to indicate the end of the log has been +passed (or the start of the log has been passed, if the direction +of traversal is backwards in time). +If the ``mode'' for the current PMAPI context (see +.BR pmSetMode (3)) +is +.B PM_MODE_INTERP +then the time origin is advanced, even when this error code is +returned. +In this way applications that position the time outside the range +defined by the records in the archive, and then commence to +.B pmFetch +will eventually see valid results once the time origin moves inside +the temporal span of the archive. +.SH ENVIRONMENT +Many of the performance metrics exported from PCP agents have the +semantics of +.I counter +meaning they are expected to be monotonically increasing. +Under some circumstances, one value of these metrics may be smaller +than the previously fetched value. +This can happen when a counter of finite precision overflows, or +when the PCP agent has been reset or restarted, or when the +PCP agent is exporting values from some +underlying instrumentation that is subject to some asynchronous +discontinuity. +.sp 0.5v +The environment variable +.B PCP_COUNTER_WRAP +may be set to indicate 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. +This ``wrapping'' behavior was the default in earlier PCP versions, but +by default has been disabled in PCP version 1.3 and later. diff --git a/man/man3/pmfetcharchive.3 b/man/man3/pmfetcharchive.3 new file mode 100644 index 0000000..25c1c6a --- /dev/null +++ b/man/man3/pmfetcharchive.3 @@ -0,0 +1,83 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000-2004 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMFETCHARCHIVE 3 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmFetchArchive\f1 \- get performance metrics directly from an archive log +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.sp +int pmFetchArchive(pmResult **\fIresult\fP); +.sp +cc ... \-lpcp +.ft 1 +.SH DESCRIPTION +.B pmFetchArchive +is a variant of +.BR pmFetch (3) +that may only be used when the current +Performance Metrics Application Programming Interface (PMAPI) +context +is associated with an archive log. +.PP +The +.I result +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 of the PMAPI context is ignored. +.PP +It is expected that +.B pmFetchArchive +would be used to create utilities that scan archive logs, +while the more common access to the archives would be via the +.BR pmFetch (3) +interface. +.PP +To skip records within the archive log, use +.BR pmSetMode (3) +to change the collection time within the current +PMAPI context, then call +.BR pmFetchArchive. +.PP +Note that the +.I result +returned by +.B pmFetchArchive +is dynamically allocated, and +must be released using +.BR pmFreeResult (3), +not +.BR free (3C). +See +.BR pmFetch (3) +and +.BR pmFreeResult (3) +for further details. +.PP +.B pmFetchArchive +returns zero on success. +.SH SEE ALSO +.BR PMAPI (3), +.BR pmFetch (3), +.BR pmFreeResult (3), +.BR pmNewContext (3), +.BR pmSetMode (3) +and +.BR pmTrimNameSpace (3). +.SH DIAGNOSTICS +.IP \f3PM_ERR_NOTARCHIVE\f1 +the current PMAPI context is not associated with an archive log diff --git a/man/man3/pmfreeeventresult.3 b/man/man3/pmfreeeventresult.3 new file mode 100644 index 0000000..6076122 --- /dev/null +++ b/man/man3/pmfreeeventresult.3 @@ -0,0 +1,66 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2014 Red Hat. +.\" Copyright (c) 2010 Ken McDonell. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMFREEEVENTRESULT 3 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmFreeEventResult\f1, +\f3pmFreeHighResEventResult\f1 \- release storage allocated for unpacked event records +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.sp +void pmFreeEventResult(pmResult **\fIrset\fP); +.br +void pmFreeHighResEventResult(pmHighResResult **\fIhrset\fP); +.sp +cc ... \-lpcp +.ft 1 +.SH DESCRIPTION +.de CW +.ie t \f(CW\\$1\f1\\$2 +.el \fI\\$1\f1\\$2 +.. +When processing event records, if +.BR pmUnpackEventRecords (3) +is used to unpack event records from a metric within a +.I pmResult +structure with a value of type +.B PM_TYPE_EVENT +then the structure returned from +.BR pmUnpackEventRecords (3) +is a NULL pointer terminated array of pointers to +.I pmResult +structures, one for each event record. +.PP +.B pmFreeEventResult +is a convenience method that frees all of the +.I pmResult +structures and the array of pointers (\c +.IR rset ). +.PP +Similarly, +.B pmFreeHighResEventResult +may be used to free the +.I pmHighResResult +structures and array returned from the +.BR pmUnpackHighResEventRecords +routine when using +.BR PM_TYPE_HIGHRES_EVENT +metrics. +.SH SEE ALSO +.BR PMAPI (3) +and +.BR pmUnpackEventRecords (3). diff --git a/man/man3/pmfreeprofile.3 b/man/man3/pmfreeprofile.3 new file mode 100644 index 0000000..8cdf0eb --- /dev/null +++ b/man/man3/pmfreeprofile.3 @@ -0,0 +1,41 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000-2004 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMFREEPROFILE 3 "PCP" "Performance Co-Pilot" +.SH NAME +\f3__pmFreeProfile\f1 \- free a PMAPI instance profile +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.br +#include <pcp/impl.h> +.sp +void __pmFreeProfile(__pmProfile *\fIprof\fP); +.sp +cc ... \-lpcp +.ft 1 +.SH DESCRIPTION +.B __pmFreeProfile +frees the storage for the PMAPI instance profile +.IR prof , +assuming the +storage was allocated using +.BR malloc (3C) +according to the scheme used in +.BR __pmDecodeProfile (3). +.SH SEE ALSO +.BR PMAPI (3) +and +.BR __pmDecodeProfile (3). diff --git a/man/man3/pmfreeresult.3 b/man/man3/pmfreeresult.3 new file mode 100644 index 0000000..8c3d570 --- /dev/null +++ b/man/man3/pmfreeresult.3 @@ -0,0 +1,61 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000-2004 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMFREERESULT 3 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmFreeResult\f1 \- release storage allocated for performance metrics values +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.sp +void pmFreeResult(pmResult *\fIresult\fP); +.sp +cc ... \-lpcp +.ft 1 +.SH DESCRIPTION +.de CW +.ie t \f(CW\\$1\f1\\$2 +.el \fI\\$1\f1\\$2 +.. +The variable sized results returned by +.BR pmFetch (3) +are allocated below the +Performance Metrics Application Programming Interface (PMAPI) +using a combination of dynamic (i.e. \c +.BR malloc (3)) +and specialized allocation strategies. +.PP +Applications should call +.B pmFreeResult +to release the storage previously allocated for +.I result +by +.BR pmFetch (3), +when the application no longer requires access to the +.CW pmResult +structure. +.PP +Under +.B no +circumstances should an application use +.CW "free(result)" +to release storage previously allocated for a +.CW pmResult +by +.BR pmFetch (3). +.SH SEE ALSO +.BR PMAPI (3) +and +.BR pmFetch (3). diff --git a/man/man3/pmgetarchiveend.3 b/man/man3/pmgetarchiveend.3 new file mode 100644 index 0000000..265a602 --- /dev/null +++ b/man/man3/pmgetarchiveend.3 @@ -0,0 +1,99 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000-2004 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMGETARCHIVEEND 3 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmGetArchiveEnd\f1 \- locate logical end of file for an archive log +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.sp +int pmGetArchiveEnd(struct timeval *\fItvp\fP); +.sp +cc ... \-lpcp +.ft 1 +.SH DESCRIPTION +Assuming the current PMAPI context +is associated with an archive log, +.B pmGetArchiveEnd +will attempt to find the logical end of file (after +the last complete record in the archive), +and return the last recorded timestamp via +.IR tvp . +This timestamp may be passed to +.BR pmSetMode (3) +to reliably position the context at the last valid +log record, e.g. in preparation for subsequent reading in +reverse chronological order. +.PP +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 +.BR pmlogger (1) +at the same time 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. +.PP +.B pmGetArchiveEnd +returns an error less than zero if the context is neither valid, +nor associated with an archive, or the archive is seriously +corrupted. +Otherwise, the return value is 0 if there has been no change of +state since the last call, or 1 if the logical end of file has +advanced since the last call. +.PP +In the absence of an error, the result returned via +.I tvp +is well-defined. +.PP +.BR pmGetArchiveEnd +preserves the positioning state of the log file prior to +this function call. +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.I /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). +Values for these variables may be obtained programmatically +using the +.BR pmGetConfig (3) +function. +.SH SEE ALSO +.BR PMAPI (3), +.BR pmFetch (3), +.BR pmFetchArchive (3), +.BR pmGetArchiveLabel (3), +.BR pmGetConfig (3), +.BR pmSetMode (3), +.BR pcp.conf (5) +and +.BR pcp.env (5). +.SH DIAGNOSTICS +.IP \f3PM_ERR_NOCONTEXT\f1 +the current PMAPI context +is either invalid, or not associated with an archive log +.IP \f3PM_ERR_LOGREC\f1 +the archive is sufficiently damaged, that not a single valid +record can be found diff --git a/man/man3/pmgetarchivelabel.3 b/man/man3/pmgetarchivelabel.3 new file mode 100644 index 0000000..3649fa6 --- /dev/null +++ b/man/man3/pmgetarchivelabel.3 @@ -0,0 +1,123 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000-2004 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMGETARCHIVELABEL 3 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmGetArchiveLabel\f1 \- fetch the label record from a performance metrics archive log +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.sp +int pmGetArchiveLabel(pmLogLabel *\fIlp\fP); +.sp +cc ... \-lpcp +.ft 1 +.SH DESCRIPTION +.de CW +.ie t \f(CW\\$1\f1\\$2 +.el \fI\\$1\f1\\$2 +.. +Within the framework of the +Performance Co-Pilot (PCP), archive logs of performance metrics values +may be accumulated and saved using the program +.BR pmlogger (1). +.PP +The routine +.B pmGetArchiveLabel +may be used to fetch the label record from an archive log that has already +been opened using +.BR pmNewContext (3), +or +.BR pmDupContext (3), +and thereby associated with the current +Performance Metrics Application Programming Interface (PMAPI) +context. +.PP +The result returned via the pointer +.I lp +is a structure that must be pre-allocated by the caller +and has the following format (defined in +.BR pmapi.h ). +.PP +.in +0.2i +.ft CW +.nf +/* + * Label Record at the start of every log file + */ +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[40]; /* $TZ at collection host */ +} pmLogLabel; +.fi +.ft 1 +.in +.PP +For an application, the most useful information from the archive label +is likely to be in the fields +.CW ll_start , +.CW ll_hostname +or +.CW ll_tz . +.PP +Note that the size of the +.CW ll_hostname +field is +.CW PM_LOG_MAXHOSTLEN +(64 bytes) +which is less than +.BR MAXHOSTNAMELEN +(see +.BR gethostbyname (3)) +on some platforms. +These semantics are necessary to retain backwards compatibility with the +PCP archive file format. +.PP +.B pmGetArchiveLabel +returns zero for success. +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.I /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). +Values for these variables may be obtained programmatically +using the +.BR pmGetConfig (3) +function. +.SH SEE ALSO +.BR pmlogger (1), +.BR PMAPI (3), +.BR pmDupContext (3), +.BR pmGetConfig (3), +.BR pmNewContext (3), +.BR pcp.conf (5) +and +.BR pcp.env (5). +.SH DIAGNOSTICS +.IP \f3PM_ERR_NOCONTEXT\f1 +the current PMAPI context +is either invalid, or not associated with an archive log diff --git a/man/man3/pmgetchildren.3 b/man/man3/pmgetchildren.3 new file mode 100644 index 0000000..a2518e4 --- /dev/null +++ b/man/man3/pmgetchildren.3 @@ -0,0 +1,130 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000-2004 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMGETCHILDREN 3 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmGetChildren\f1 \- return the descendent nodes of a PMNS node +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.sp +.nf +int pmGetChildren(const char *\fIname\fP, char ***\fIoffspring\fP); +.fi +.sp +cc ... \-lpcp +.ft 1 +.SH DESCRIPTION +.de CW +.ie t \f(CW\\$1\f1\\$2 +.el \fI\\$1\f1\\$2 +.. +Given a fully qualified pathname to a node in the current Performance +Metrics Name Space (PMNS), as identified by +.IR name , +.B pmGetChildren +returns via +.I offspring +a list of the relative names of +all of the immediate descendent nodes of +.I name +in the current PMNS. +.PP +As a +special case, if +.I name +is an empty string (i.e.\f3""\f1), the immediate descendants of +the root node in the PMNS will be returned. +.PP +Normally, +.B pmGetChildren +will return the number of descendent names discovered, else a value +less than zero for an error. +The value zero indicates that +.I name +is a valid metric name, i.e. is associated with a leaf node in the PMNS. +.PP +The resulting list of pointers +.I offspring +.B and +the values +(the relative names) that the pointers reference will have been +allocated by +.B pmGetChildren +with a single call to +.BR malloc (3C), +and it is the +responsibility of the +.B pmGetChildren +caller to +.BR free (\c +.IR offspring ) +to release the space +when it is no longer required. +.PP +When an error occurs, or +.I name +is a leaf node (i.e. the result of +.B pmGetChildren +is less than one), +.I offspring +is undefined (no space will have been +allocated, and so calling +.BR free (3C) +is a singularly bad idea). +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.I /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). +Values for these variables may be obtained programmatically +using the +.BR pmGetConfig (3) +function. +.SH SEE ALSO +.BR PMAPI (3), +.BR pmGetChildrenStatus (3), +.BR pmGetConfig (3), +.BR pmLoadASCIINameSpace (3), +.BR pmLoadNameSpace (3), +.BR pmLookupName (3), +.BR pmNameID (3), +.BR pcp.conf (5), +.BR pcp.env (5) +and +.BR pmns (5). +.SH DIAGNOSTICS +.IP \f3PM_ERR_NOPMNS\f1 +Failed to access a PMNS for operation. +Note that if the application hasn't a priori called pmLoadNameSpace(3) +and wants to use the distributed PMNS, then a call to +.B pmGetChildren +must be made inside a current context. +.IP \f3PM_ERR_NAME\f1 +The pathname +.I name +is not valid in the current PMNS +.IP \f3PM_ERR_*\f1 +Other diagnostics are for protocol failures when +accessing the distributed PMNS. diff --git a/man/man3/pmgetchildrenstatus.3 b/man/man3/pmgetchildrenstatus.3 new file mode 100644 index 0000000..155d6d0 --- /dev/null +++ b/man/man3/pmgetchildrenstatus.3 @@ -0,0 +1,152 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000-2004 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMGETCHILDRENSTATUS 3 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmGetChildrenStatus\f1 \- return the descendent nodes of a PMNS node and their respective status +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.sp +.ad l +.hy 0 +.in +8n +.ti -8n +int pmGetChildrenStatus(const char *\fIname\fP, char ***\fIoffspring\fP, int\ **\fIstatus\fP); +.sp +.in +.hy +.ad +cc ... \-lpcp +.ft 1 +.SH DESCRIPTION +.de CW +.ie t \f(CW\\$1\f1\\$2 +.el \fI\\$1\f1\\$2 +.. +Given a fully qualified pathname to a node in the current Performance +Metrics Name Space (PMNS), as identified by +.IR name , +.B pmGetChildrenStatus +returns via +.I offspring +a list of the relative names of +all of the immediate descendent nodes of +.I name +in the current PMNS. +.PP +As a +special case, if +.I name +is an empty string (i.e.\f3""\f1), the immediate descendants of +the root node in the PMNS will be returned. +.PP +If +.IR status +is not NULL, then +.B pmGetChildrenStatus +will also return the status of each child via +.IR status. +The status will refer to either a leaf node (with value +.B PMNS_LEAF_STATUS +) or a non-leaf node (with value +.B PMNS_NONLEAF_STATUS +). +.PP +Normally, +.B pmGetChildrenStatus +will return the number of descendent names discovered, else a value +less than zero for an error. +The value zero indicates that +.I name +is a valid metric name, i.e. is associated with a leaf node in the PMNS. +.PP +The resulting list of pointers +.I offspring +.B and +the values +(the relative names) that the pointers reference will have been +allocated by +.B pmGetChildrenStatus +with a single call to +.BR malloc (3C), +and it is the +responsibility of the +.B pmGetChildrenStatus +caller to +.BR free (\c +.IR offspring ) +to release the space +when it is no longer required. +The same holds true for the +.I status +array. +.PP +When an error occurs, or +.I name +is a leaf node (i.e. the result of +.B pmGetChildrenStatus +is less than one), both +.I offspring +and +.I status +are undefined (no space will have been +allocated, and so calling +.BR free (3C) +is a singularly bad idea). +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.I /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). +Values for these variables may be obtained programmatically +using the +.BR pmGetConfig (3) +function. +.SH SEE ALSO +.BR PMAPI (3), +.BR pmGetChildren (3), +.BR pmGetConfig (3), +.BR pmLoadASCIINameSpace (3), +.BR pmLoadNameSpace (3), +.BR pmLookupName (3), +.BR pmNameID (3), +.BR pcp.conf (5), +.BR pcp.env (5) +and +.BR pmns (5). +.SH DIAGNOSTICS +.IP \f3PM_ERR_NOPMNS\f1 +Failed to access a PMNS for operation. +Note that if the application hasn't a priori called pmLoadNameSpace(3) +and wants to use the distributed PMNS, then a call to +.B pmGetChildrenStatus +must be made inside a current context. +.IP \f3PM_ERR_NAME\f1 +The pathname +.I name +is not valid in the current PMNS +.IP \f3PM_ERR_*\f1 +Other diagnostics are for protocol failures when +accessing the distributed PMNS. diff --git a/man/man3/pmgetconfig.3 b/man/man3/pmgetconfig.3 new file mode 100644 index 0000000..0fdbe10 --- /dev/null +++ b/man/man3/pmgetconfig.3 @@ -0,0 +1,124 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2012 Red Hat. +.\" Copyright (c) 2000 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.TH PMGETCONFIG 3 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmGetConfig\f1 \- return Performance Co-Pilot configuration variable +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.br +char *pmGetConfig(const char *\fIvariable\fP); +.sp +#include <pcp/impl.h> +.br +char *__pmGetAPIConfig(const char *\fIfeature\fP); +.sp +cc ... \-lpcp +.ft 1 +.SH DESCRIPTION +The +.B pmGetConfig +function searches for +.I variable +first in the environment and then, if not found, in +the Performance Co-Pilot (PCP) configuration file +and returns the string result. +If +.I variable +is not already in the environment, +it is added with a call to +.BR putenv (3) +before returning. +.PP +The default location of the PCP configuration file is +.B /etc/pcp.conf +but this may be changed by setting +.B PCP_CONF +in the environment to a new location, +as described in +.BR pcp.conf (5). +.PP +The internal +.B __pmGetAPIConfig +function reports on features of the PCP library. +It can be used to query support for multi-threading, security extensions, +and other features. +.PP +The +.BR pmconfig (1) +utility provides command line access to both of these interfaces, and also +provides a mechanism for listing all available +.B variables +and +.B features +that are valid arguments to these routines. +.SH "RETURN VALUE" +If +.I variable +is not found in either the environment nor the PCP configuration file then +the return value is an empty string. +If the +PCP configuration file is not found +then a fatal error message is printed and the process will +.BR exit (2) +\- although this sounds drastic, it is the only course of action available +because the PCP configuration/installation is fatally flawed. +.PP +If the +.B pmGetConfig +function returns a non-empty string, +the returned value points into the environment and so changing +it is a bad idea. +This function returns the same type as the +.BR getenv (3) +function (which should probably be a +.IR "const char *" ). +.PP +The +.B __pmGetAPIConfig +routine on the other hand returns NULL on failure to lookup the requested +.IR feature . +It does not modify the environment, and returns a pointer to a static +read-only string which also should not be modified or freed by the caller. +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.I /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). +Values for these variables may be obtained programmatically +using the +.BR pmGetConfig (3) +function. +.SH SEE ALSO +.BR PCPIntro (1), +.BR pmconfig (1), +.BR exit (2), +.BR PMAPI (3), +.BR getenv (3C), +.BR putenv (3C), +.BR pcp.conf (5), +.BR pcp.env (5) +and +.BR environ (5). diff --git a/man/man3/pmgetcontexthostname.3 b/man/man3/pmgetcontexthostname.3 new file mode 100644 index 0000000..5826861 --- /dev/null +++ b/man/man3/pmgetcontexthostname.3 @@ -0,0 +1,114 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2013 Red Hat. +.\" Copyright (c) 2000-2004 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMGETCONTEXTHOSTNAME 3 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmGetContextHostName\f1, +\f3pmGetContextHostName_r\f1 \- return the hostname associated with a Performance Co-Pilot context +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.sp +const char *pmGetContextHostName(int \fIid\fP); +.br +char *pmGetContextHostName_r(int \fIid\fP, char *\fIbuf\fP, int \fIbuflen\fP); +.sp +cc ... \-lpcp +.ft 1 +.SH DESCRIPTION +Given a valid PCP context identifier previously created with +.BR pmNewContext (3) +or +.BR pmDupContext (3), +the +.B pmGetContextHostName +function returns the hostname associated with +.IR id . +The +.B pmGetContextHostName_r +function does the same, but stores the result in a user-supplied buffer +.I buf +of length +.IR buflen , +which should have room for at least +.B MAXHOSTNAMELEN +bytes. +.PP +If the context +.I id +is associated with an archive source of data, the +hostname returned is extracted from the archive label using +.BR pmGetArchiveLabel (3). +.PP +For live contexts, an attempt will first be made to retrieve +the hostname from the PCP collector system using +.BR pmFetch (3) +with the +.I pmcd.hostname +metric. +This allows client tools using this interface to retrieve an +accurate host identifier even in the presence of port forwarding +and tunnelled connections. +.PP +Should this not succeed, then a fallback method is used. +For local contexts \- with local meaning any of DSO, ``localhost'' +or Unix domain socket connection \- a hostname will be sought via +.BR gethostname (3). +For other contexts, the hostname extracted from the initial +context host specification will be used. +.SH "RETURN VALUE" +If +.I id +is not a valid PCP context identifier, +the returned hostname is a zero length string. +.SH NOTES +.B pmGetContextHostName +returns a pointer to a static buffer, +so the returned value is only valid until the next call to +.B pmGetContextHostName +and hence is not thread-safe. +Multi-threaded applications should use +.B pmGetContextHostName_r +instead. +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.I /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). +Values for these variables may be obtained programmatically +using the +.BR pmGetConfig (3) +function. +.SH SEE ALSO +.BR PCPIntro (1), +.BR PMAPI (3), +.BR gethostname (3), +.BR pmDupContext (3), +.BR pmFetch (3), +.BR pmGetArchiveLabel (3), +.BR pmNewContext (3), +.BR pcp.conf (5) +and +.BR pcp.env (5). diff --git a/man/man3/pmgetindom.3 b/man/man3/pmgetindom.3 new file mode 100644 index 0000000..f9ebf14 --- /dev/null +++ b/man/man3/pmgetindom.3 @@ -0,0 +1,113 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000-2004 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMGETINDOM 3 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmGetInDom\f1 \- get instance identifiers for a performance metrics instance domain +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.sp +.nf +int pmGetInDom(pmInDom \fIindom\fP, int **\fIinstlist\fP, char ***\fInamelist\fP); +.fi +.sp +cc ... \-lpcp +.ft 1 +.SH DESCRIPTION +.de CW +.ie t \f(CW\\$1\f1\\$2 +.el \fI\\$1\f1\\$2 +.. +In the current +Performance Metrics Application Programming Interface (PMAPI) +context, +locate the description of the instance domain +.IR indom , +and return via +.I instlist +the internal instance identifiers for all instances, +and via +.I namelist +the full external identifiers for all instances. +The number of instances found is returned as the function value +(else less than zero to indicate an error). +.PP +The value for the instance domain +.I indom +is typically extracted from a +.CW pmDesc +structure, following a call to +.BR pmLookupDesc (3) +for a particular performance metric. +.PP +The resulting lists of instance identifiers (\c +.I instlist +and +.IR namelist ), +and the names that the elements of +.I namelist +point to, will have been allocated by +.B pmGetInDom +with two calls to +.BR malloc (3C), +and it is the responsibility of the caller to +.CW free(instlist) +and +.CW free(namelist) +to release the space when it is no longer required. +.PP +When the result of +.B pmGetInDom +is less than one, both +.I instlist +and +.I namelist +are undefined (no space will have been allocated, +and so calling +.BR free (3C) +is a singularly bad idea). +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.I /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). +Values for these variables may be obtained programmatically +using the +.BR pmGetConfig (3) +function. +.SH SEE ALSO +.BR PMAPI (3), +.BR pmGetConfig (3), +.BR pmGetInDomArchive (3), +.BR pmLookupDesc (3), +.BR pmLookupInDom (3), +.BR pmNameInDom (3), +.BR pcp.conf (5) +and +.BR pcp.env (5). +.SH DIAGNOSTICS +.IP \f3PM_ERR_INDOM\f1 +.I indom +is not a valid instance domain identifier diff --git a/man/man3/pmgetindomarchive.3 b/man/man3/pmgetindomarchive.3 new file mode 100644 index 0000000..4b0d714 --- /dev/null +++ b/man/man3/pmgetindomarchive.3 @@ -0,0 +1,120 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000-2004 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMGETINDOMARCHIVE 3 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmGetInDomArchive\f1 \- get instance identifiers for a performance metrics instance domain +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.sp +int pmGetInDomArchive(pmInDom \fIindom\fP, int **\fIinstlist\fP, char ***\fInamelist\fP); +.sp +cc ... \-lpcp +.ft 1 +.SH DESCRIPTION +.de CW +.ie t \f(CW\\$1\f1\\$2 +.el \fI\\$1\f1\\$2 +.. +Provided the current +Performance Metrics Application Programming Interface (PMAPI) +context is associated with an archive log, +.B pmGetInDomArchive +will scan the union of all the instance domain metadata +for the instance domain +.IR indom , +and return via +.I instlist +the internal instance identifiers for all instances, +and via +.I namelist +the full external identifiers for all instances. +.PP +This routine is a specialized version of the more general PMAPI +routine +.BR pmGetInDom . +.PP +The number of instances found is returned as the function value +(else less than zero to indicate an error). +.PP +The value for the instance domain +.I indom +is typically extracted from a +.CW pmDesc +structure, following a call to +.BR pmLookupDesc (3) +for a particular performance metric. +.PP +The resulting lists of instance identifiers (\c +.I instlist +and +.IR namelist ), +and the names that the elements of +.I namelist +point to, will have been allocated by +.B pmGetInDomArchive +with two calls to +.BR malloc (3C), +and it is the responsibility of the caller to +.CW free(instlist) +and +.CW free(namelist) +to release the space when it is no longer required. +.PP +When the result of +.B pmGetInDomArchive +is less than one, both +.I instlist +and +.I namelist +are undefined (no space will have been allocated, +and so calling +.BR free (3C) +is a singularly bad idea). +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.I /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). +Values for these variables may be obtained programmatically +using the +.BR pmGetConfig (3) +function. +.SH SEE ALSO +.BR PMAPI (3), +.BR pmGetConfig (3), +.BR pmGetInDom (3), +.BR pmLookupDesc (3), +.BR pmLookupInDomArchive (3), +.BR pmNameInDomArchive (3), +.BR pcp.conf (5) +and +.BR pcp.env (5). +.SH DIAGNOSTICS +.IP \f3PM_ERR_NOTARCHIVE\f1 +the current PMAPI context is not associated with an archive log +.IP \f3PM_ERR_INDOM_LOG\f1 +.I indom +is not a defined instance domain identifier for the archive log diff --git a/man/man3/pmgetoptions.3 b/man/man3/pmgetoptions.3 new file mode 100644 index 0000000..a713b2b --- /dev/null +++ b/man/man3/pmgetoptions.3 @@ -0,0 +1,481 @@ +.\" +.\" Copyright (c) 2014 Red Hat. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.TH PMGETOPTIONS 3 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmgetopt_r\f1, +\f3pmGetOptions\f1, +\f3pmGetContextOptions\f1, +\f3pmFreeOptions\f1, +\f3pmUsageMessage\f1 \- command line handling for PMAPI tools +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.sp +.br +int pmgetopt_r(int \fIargc\fP, char *const *\fIargv\fP, pmOptions *\fIopts\fP); +.br +int pmGetOptions(int \fIargc\fP, char *const *\fIargv\fP, pmOptions *\fIopts\fP); +.br +int pmGetContextOptions(int \fIctx\fP, pmOptions *\fIopts\fP); +.br +void pmUsageMessage(pmOptions *\fIopts\fP); +.br +void pmFreeOptions(pmOptions *\fIopts\fP); +.fi +.sp +cc ... \-lpcp +.ft 1 +.SH DESCRIPTION +The +.B pmGetOptions +function provides command line option processing services for both +monitor and collector +.BR PMAPI (3) +tools. +It is modelled on the thread-safe variants of the GNU +.BR getopt_long (3) +API, and primarily differs in its focus on providing generalised +processing for the (de-facto) standard PCP command line options +described in +.BR PCPIntro (1). +These common options include the host and archive specification, +time windows, timezones, sample counts, time intervals, and so on. +.PP +The primary interface is +.BR pmGetOptions , +which should be passed the +.I argc +argument count and +.I argv +array, as passed to the +.IR main() +function on program invocation. +The final +.I opts +argument describes the set of long and short options the tools is +prepared to process, and other metadata regarding how those options +should be processed. +.PP +The +.B pmgetopt_r +interface, used internally by +.BR pmGetOptions , +behaves in a similar fashion, but it does not perform any common +option processing. +It is more suited to PCP collector processes, whereas PCP monitor +tools tend to use +.BR pmGetOptions . +.PP +The +.I opts +argument consists of an array of +.I pmLongOpts +entries describing the arguments, as well as the enclosing +.I pmOptions +struct, which are defined as follows (internal fields are not +presented, for brevity): +.PP +.sp 0.5v +.ft CW +.nf +.in +0.25i +typedef struct { + const char * long_opt; + int has_arg; + int short_opt; + const char * argname; + const char * message; +} pmLongOptions; + +typedef struct { + int version; + int flags; + const char * short_options; + pmLongOptions * long_options; + const char * short_usage; + pmOptionOverride override; + + int index; + int optind; + int opterr; + int optopt; + char *optarg; + /* [internal fields, undocumented] */ + + int errors; + int context; /* PM_CONTEXT_{HOST,ARCHIVE,LOCAL} */ + int nhosts; + int narchives; + char ** hosts; + char ** archives; + struct timeval start; + struct timeval finish; + struct timeval origin; + struct timeval interval; + char * align_optarg; + char * start_optarg; + char * finish_optarg; + char * origin_optarg; + char * guiport_optarg; + char * timezone; + int samples; + int guiport; + int padding; + unsigned int guiflag : 1; + unsigned int tzflag : 1; + unsigned int nsflag : 1; + unsigned int Lflag : 1; + unsigned int zeroes : 28; +} pmOptions; +.in -0.25i +.fi +.ft R +.PP +The initial +.I flags +and +.I version +fields describe how the rest of the pmOptions structure is to be +interpreted. +These fields can be zeroed, specifying a default interpretation. +Alternatively, the PMAPI_VERSION macro can be used to specify the +API level to use (currently, values of 2 or less are allowed). +The +.I flags +field can be used to modify option processing behaviour as +described in the ``FLAGS VALUES'' section below. +.PP +The array of +.I long_options +pmLongOpts structures must be terminated by a sentinel and the +PMAPI_OPTIONS_END macro can be used to effect this termination. +Individual records within the +.I long_options +array can be of two types \- options headers, or actual options. +An options header is constructed using the PMAPI_OPTIONS_HEADER +macro, and is used for usage message option grouping. +Free form text can be inserted into the usage message at any +point using the PMAPI_OPTIONS_TEXT macro \- this is intended +for additional explanatory text covering detailed usage that +is beyond the scope of the individual headers or options. +Otherwise, the array entry specifies an option. +These should be named (\c +.IR long_opt ) +if a long-option form is allowed, +specify whether or not they take an argument (\c +.IR has_arg ), +specify the single character variant argument (\c +.IR short_opt ) +if a short-option form is allowed, +and finally specify how to present the option in the usage message. +This latter component consists of a short, one-word description of +the optional argument (\c +.IR argname ) +and a one-line description of what the command-line option does (\c +.IR message ). +.PP +The +.I short_usage +string is also used only when constructing the usage message. +It forms the component of the usage message that follows the +program name (i.e. \c +.IR argv[0] ). +.PP +The optional +.I short_options +string is the normal +.I getopt +command-line option specification string, using individual +characters (those with arguments are designated as such +using the ':' character) \- as used by all +.I getopt +implementations. +.PP +A facility is provided to extend the existing set of common options +with additional options, as well as to re-task the standard options +into non-standard roles for individual tools. +The latter is achieved using the +.I override +method, which allows a callback function to be provided which will +be called on receipt of every argument, prior to common processing. +If this callback returns a non-zero value the common processing will +be short-circuited for that option, otherwise processing continues. +Thus, aach client tool is free to choose exactly which of the standard +options they wish to support \- this can be all, some, or none, and +no matter what they choose, each tool always has access to the long +option parsing capability and the usage message generation facility. +.PP +The remaining pmOptions structure fields are filled in as a result +of processing the arguments, and are largely self-explanatory. +Further discussion of these is deferred to the ``FLAGS VALUES'' +section below. +The +.I error +field contains a count of errors detected during option processing. +These can be either usage or runtime errors, as indicated by the +.I flags +field (set, and passed out to the caller). +Typically, a command line tool will fail to start successfully and +will produce an error message (e.g. via +.BR pmUsageMessage ) +if the +.I error +field is non-zero at the end of either +.B pmGetOptions +or +.BR pmGetContextOptions . +.PP +Some command line option post-processing can only be performed once +the tool has established a PMAPI context via +.BR pmNewContext (3). +This processing includes use of context-aware timezones (\f3\-z\f1), +and time window processing (\f3\-A\f1, \f3\-O\f1, \f3\-S\f1, \f3\-T\f1) +that may be affected by the timezone, for example. +The +.B pmGetContextOptions +function is available for such situations, and it completes any +remaining processing of +.I opts +with respect to the +.I ctx +context identifier given. +.PP +The +.B pmUsageMessage +function generates a usage message for the tool, and included both +standard PCP options and custom options for each tool, as specified +by the pmLongOptions array. +It supports grouping of options (via PMAPI_OPTIONS_HEADER) as well +as neat formatting of all options \- short and long \- their +arguments, and individual explanatory messages. +It will build this usage message using +.BR pmprintf (3) +upon which it will issue a single +.BR pmflush (3) +before returning to the caller, provided the PM_OPTFLAG_USAGE_ERR +flag is set in +.IR flags , +which will happen automatically during option parsing, when usage +errors are detected. +.PP +In certain situations, such as recording lists of host specifications +or PCP archive paths, the +.B pmGetOptions +routine may allocate memory, and store pointers to it within +.IR opts . +Should a program wish to free this memory before exiting, it can +use the +.B pmFreeOptions +routine to do so. +This is safe to call irrespective of whether memory was allocated +dynamically, provided that +.I opts +was zeroed initially. +.SH "FLAGS VALUES" +.TP +.B PM_OPTFLAG_INIT +Used internally within the library to indicate initialisation has been +done, so that on subsequent calls it will not be done again. +.TP +.B PM_OPTFLAG_DONE +Used primarily internally within the library to indicate that the final +option processing has been completed. +This processing involves cross-referencing a number of the options, to +check for mutual exclusion, for example. +There may be other post-processing at this stage also, provided it does +not require a PMAPI context. +.TP +.B PM_OPTFLAG_MULTI +Allow more than one host or archive to be specified. +The default is to allow one source of metrics only, however some of the +more sophisticated tools permit multiple metric sources. +See also +.BR PM_OPTFLAG_MIXED . +.TP +.B PM_OPTFLAG_USAGE_ERR +Indicates that the library has detected a command-line usage error. +This is an error such as when an option requires an argument but none +is supplied, or conflicting options are specified (such as \f3\-s\f1 +and \f3-T\f1). +.TP +.B PM_OPTFLAG_RUNTIME_ERR +Indicates that the library has detected an error at run time. +This is an error such as failing to retrieve timezone information +from +.B pmcd (1) +or +failing to load an alternate metric namespace from a local file +(via the \f3-n\f1 option). +.TP +.B PM_OPTFLAG_EXIT +Indicates a suggestion from the library that the tool exit cleanly. +This is used when the version number is requested, for example (the +\f3\-V\f1 option and PMOPT_VERSION macro). +.TP +.B PM_OPTFLAG_POSIX +Use strict POSIX command line argument handling. +This means options and following arguments will not be reordered, +so additional options cannot follow command line arguments. +This may be important for tools where the arguments can be negative +numbers, for example, as these should not be treated as command line +options in this case. +.TP +.B PM_OPTFLAG_MIXED +Allow both live and archive metric sources to be specified. +The default is to allow one type of metric context only, however some +of the more sophisticated tools permit multiple context types. +See also +.BR PM_OPTFLAG_MULTI . +.TP +.B PM_OPTFLAG_ENV_ONLY +Many options can be specified through the either the command line +or from similarly-named environment variables. +This flag disables all argument parsing, and only changes +.I opts +based on the environment variables. +This may be useful for tools wishing to ensure no command line option +conflicts occur between their own set and the standard PCP option set +(such as an existing tool, reimplemented using PMAPI services). +.TP +.B PM_OPTFLAG_LONG_ONLY +Only process long options, not short options. +.TP +.B PM_OPTFLAG_BOUNDARIES +The default +.B pmGetOptions +behaviour is to parse the time window options (namely, \f3\-A\f1, +\f3\-O\f1, \f3\-S\f1 and \f3\-T\f1), only if one of those options +has been specified on the command line. +However, this flag can be used (particularly with archive contexts) +to find the +.I start +and +.I finish +times associated with the context(s) even if no time window options +were specified. +In the case of multiple archives, the time window is defined as the +time window spanning all of the archives. +.TP +.B PM_OPTFLAG_STDOUT_TZ +The timezone being used will be reported on the standard output +stream during option parsing. +The default behaviour is to not report, but simply return timezone +information via the +.I timezone +(\f3\-Z\f1) +and +.I tzflag +(\f3\-z\f1) +fields in the +.I opts +structure. +.TP +.B PM_OPTFLAG_NOFLUSH +The final +.B pmflush +call issued by +.B pmUsageMessage +will be skipped if this flag is set. +This is useful in situations where the caller wishes to append +additional test to the generated usage message before flushing. +.TP +.B PM_OPTFLAG_QUIET +Suppress messages from +.B pmgetopt_r +about unrecognised command line options. +This is the equivalent to setting the +.I opterr +field in the +.I opt +parameter (which mimics the +.B getopt +variable of the same name). +.SH "RETURN VALUE" +The +.B pmGetOptions +function returns either when it detects a command-line option that +is not one of the standard PCP set, or when the end of the command +line options has been reached (at which point -1 is returned). +Both the +.B pmgetopt_r +and +.B pmGetOptions +routines return control to the caller in the same way that a regular +.B getopt +call would, with the return value indicating either the end of all +processing (-1), or the single character form of the option currently +being processed, or zero for the special long-option-only case. +For all option-processing cases, the +.I opts +structure is returned containing filled out +.IR optarg , +.IR opterr , +.IR optopt , +.IR optind , +and +.I index +fields as normal (do +.B NOT +use the global optarg or optind from your platform C library, +these will +.B NOT +be modified). +.PP +.B pmGetOptions +does not return to the caller when any of the standard PCP options are +being processed (although the +.I override +mechanism can be used to still detect such options if needed). +.PP +The +.B pmGetContextOptions +function returns zero on success, or a negative PCP error code +on failure. +The +.I error +field within the +.I +opts +parameter will also be non-zero in the latter case. +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.I /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). +Values for these variables may be obtained programmatically +using the +.BR pmGetOptions (3) +function. +.SH SEE ALSO +.BR PCPIntro (1), +.BR pmcd (1), +.BR pminfo (1), +.BR pmstat (1), +.BR getopt (3), +.BR getopt_long (3), +.BR pmNewContext (3), +.BR pmconfig (3), +.BR pmprintf (3), +.BR pmflush (3) +and +.BR PMAPI (3). diff --git a/man/man3/pmgetpmnslocation.3 b/man/man3/pmgetpmnslocation.3 new file mode 100644 index 0000000..0c1bd78 --- /dev/null +++ b/man/man3/pmgetpmnslocation.3 @@ -0,0 +1,69 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000-2004 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMGETPMNSLOCATION 3 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmGetPMNSLocation\f1 \- determine the location of the currently used PMNS +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.sp +int pmGetPMNSLocation(void); +.sp +cc ... \-lpcp +.ft 1 +.SH DESCRIPTION +If an application needs to know where the Performance Metrics Name Space +(PMNS) is coming from then +.B pmGetPMNSLocation +will return whether it is from an archive, \f3PMNS_ARCHIVE\f1, +or from a local PMNS file, \f3PMNS_LOCAL\f1, or from a remote pmcd, +\f3PMNS_REMOTE\f1. +.P +This information may be useful in determining an appropriate error message +depending on the PMNS' location. +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.I /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). +Values for these variables may be obtained programmatically +using the +.BR pmGetConfig (3) +function. +.SH SEE ALSO +.BR PMAPI (3), +.BR pmGetConfig (3), +.BR pmLoadASCIINameSpace (3), +.BR pmLoadNameSpace (3), +.BR pmTrimNameSpace (3), +.BR pcp.conf (5), +.BR pcp.env (5) +and +.BR pmns (5). +.SH DIAGNOSTICS +.IP \f3PM_ERR_NOPMNS\f1 +If is not possible to determine where the location of the PMNS is. +This could be due to problems with the current context or being +unable to load a local PMNS. diff --git a/man/man3/pmiaddinstance.3 b/man/man3/pmiaddinstance.3 new file mode 100644 index 0000000..4d4f026 --- /dev/null +++ b/man/man3/pmiaddinstance.3 @@ -0,0 +1,84 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2010 Ken McDonell. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMIADDINSTANCE 3 "" "Performance Co-Pilot" +.SH NAME +\f3pmiAddInstance\f1 \- add an element to an instance domain in a LOGIMPORT context +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.br +#include <pcp/impl.h> +.br +#include <pcp/import.h> +.sp +int pmiAddInstance(pmInDom \fIindom\fP, const char *\fIinstance\fP, int \fIinst\fP); +.sp +cc ... \-lpcp_import \-lpcp +.ft 1 +.SH "Perl SYNOPSIS" +.ft 3 +use PCP::LogImport; +.sp +pmiAddInstance($\fIindom\fP, $\fIinstance\fP, $\fIinst\fP); +.ft 1 +.SH DESCRIPTION +As part of the Performance Co-Pilot Log Import API (see +.BR LOGIMPORT (3)), +.B pmiAddInstance +adds a new element to the instance domain identified by +.IR indom . +.PP +.I indom +would normally be constructed using the +.B pmInDom_build +macro, e.g. pmInDom_build(PMI_DOMAIN,0) for the first instance domain +in the Performance Metrics Domain PMI_DOMAIN +(which is the default for all meta data created by the LOGIMPORT library). +.PP +The new instance must have both an external name (\c +.IR instance ) +and an internal instance identifier (\c +.IR inst ) +that is unique across all instances in the +.I indom +instance domain. +There is a special ``uniqueness rule'' for +.I instance +that is imposed by +.BR pmLookupInDom (3), +namely that the external instance name must be unique in the leading +non-space characters, e.g. the instance names ``foo'' and ``foo bar'' +are considered the same by this rule and not allowed in the same +instance domain, but ``foo'' and ``foobar'' would be allowed. +.PP +Once defined, the external instance name can be used in calls to +.BR pmiGetHandle (3) +and/or +.BR pmiPutValue (3) +with the name of a metric defined over the same instance domain. +.SH DIAGNOSTICS +.B pmiAddInstance +returns zero on success else a negative value that can be turned into an +error message by calling +.BR pmiErrStr (3). +.SH SEE ALSO +.BR LOGIMPORT (3), +.BR pmiAddMetric (3), +.BR pmiErrStr (3), +.BR pmiGetHandle (3), +.BR pmiPutValue (3) +and +.BR pmLookupInDom (3). diff --git a/man/man3/pmiaddmetric.3 b/man/man3/pmiaddmetric.3 new file mode 100644 index 0000000..ac0b39d --- /dev/null +++ b/man/man3/pmiaddmetric.3 @@ -0,0 +1,133 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2010 Ken McDonell. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMIADDMETRIC 3 "" "Performance Co-Pilot" +.SH NAME +\f3pmiAddMetric\f1 \- add a new metric definition to a LOGIMPORT context +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.br +#include <pcp/impl.h> +.br +#include <pcp/import.h> +.sp +.ad l +.hy 0 +.in +8n +.ti -8n +int pmiAddMetric(const char *\fIname\fP, pmID \fIpmid\fP, int\ \fItype\fP, pmInDom\ \fIindom\fP, int\ \fIsem\fP, pmUnits\ \fIunits\fP); +.sp +.in +.hy +.ad +cc ... \-lpcp_import \-lpcp +.ft 1 +.SH "Perl SYNOPSIS" +.ft 3 +use PCP::LogImport; +.sp +pmiAddMetric($\fIname\fP, $\fIpmid\fP, $\fItype\fP, $\fIindom\fP, $\fIsem\fP, $\fIunits\fP); +.ft 1 +.SH DESCRIPTION +As part of the Performance Co-Pilot Log Import API (see +.BR LOGIMPORT (3)), +.B pmiAddMetric +is used to define a new metric. The metric's +.I name +must follow the naming conventions described in +.BR PCPIntro (1) +and should be unique for each LOGIMPORT context. +.PP +The other arguments are in effect the fields of a +.B pmDesc +structure. +Refer to +.BR pmLookupDesc (3) +for a complete description of the values and semantics of the +components of this +structure, and hence the valid argument values for +.BR pmiAddMetrics . +.PP +The internal identifier for the metric may be given using the +.I pmid +argument and must be unique for each LOGIMPORT context. +The value for +.I pmid +which would typically be constructed using the +.B pmid_build +macro, e.g. pmid_build(PMI_DOMAIN, 0, 3) for the fourth metric in +first ``cluster'' of metrics in the Performance Metrics Domain PMI_DOMAIN +(which is the default for all meta data created by the LOGIMPORT library). +Alternatively, +.I pmid +may be +.B PM_IN_NULL +and +.B pmiAddMetric +will assign a unique +.I pmid +(although this means the +.I pmid +remains opaque and the application must use +.BR pmiPutValue (3) +or +.BR pmiPutValueHandle (3) +and cannot use +.BR pmiPutResult (3) +to add data values to the PCP archive). +.PP +.I type +defines the data type of the metric and must be one of the +.B PM_TYPE_... +values +defined in +.BR <pcp/import.h> . +.PP +The instance domain for the metric is defined by +.I indom +and may be +.B PM_INDOM_NULL +for a metric with a singular value, else the value for +.I indom +would normally be constructed using the +.B pmInDom_build +macro, e.g. pmInDom_build(LOGIMPORT,0) for the first instance domain +in the Performance Metrics Domain LOGIMPORT +(which is the default for all meta data created by the LOGIMPORT library). +Multiple metrics can share the same instance domain if they have +values for a similar (or more usually, identical) set of instances. +.PP +The semantics of the metric (counter, instantaneous value, etc.) is +specified by the +.I sem +argument which would normally be the result of a call to the +convenience constructor method +.BR pmiUnits (3). +.SH DIAGNOSTICS +.B pmiAddMetric +returns zero on success else a negative value that can be turned into an +error message by calling +.BR pmiErrStr (3). +.SH SEE ALSO +.BR PCPIntro (1), +.BR LOGIMPORT (3), +.BR pmiErrStr (3), +.BR pmiPutResult (3), +.BR pmiPutValue (3), +.BR pmiPutValueHandle (3), +.BR pmiUnits (3) +and +.BR pmLookupDesc (3). diff --git a/man/man3/pmidstr.3 b/man/man3/pmidstr.3 new file mode 100644 index 0000000..1e49fa6 --- /dev/null +++ b/man/man3/pmidstr.3 @@ -0,0 +1,107 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000-2004 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMIDSTR 3 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmIDStr\f1, +\f3pmIDStr_r\f1 \- convert a performance metric identifier into a string +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.sp +const char *pmIDStr(pmID \fIpmid\fP); +.br +char *pmIDStr_r(pmID \fIpmid\fP, char *\fIbuf\fP, int \fIbuflen\fP); +.sp +cc ... \-lpcp +.ft 1 +.SH DESCRIPTION +.de CW +.ie t \f(CW\\$1\f1\\$2 +.el \fI\\$1\f1\\$2 +.. +For use in error and diagnostic messages, +.B pmIDStr +returns a `human readable' version of +the specified Performance Metric Identifier (PMID). +The +.B pmIDStr_r +function does the same, but stores the result in a user-supplied buffer +.I buf +of length +.IR buflen , +which should have room for at least 20 bytes. +.PP +Internally, a PMID is +encoded as follows; +.PP +.ft CW +.nf +.in +0.5i +typedef struct { + int pad:2; + unsigned int domain:8; + unsigned int cluster:12; + unsigned int item:10; +} __pmID_int; +.in +.fi +.ft 1 +.PP +.B pmIDStr +returns a string with each of the +.CW domain , +.CW cluster +and +.CW item +subfields appearing as decimal numbers, separated by periods. +.PP +The string value result from +.B pmIDStr +is held in a single static buffer, so the returned value is +only valid until the next call to +.BR pmIDStr . +.SH NOTES +.B pmIDStr +returns a pointer to a static buffer and hence is not thread-safe. +Multi-threaded applications should use +.B pmIDStr_r +instead. +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.I /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). +Values for these variables may be obtained programmatically +using the +.BR pmGetConfig (3) +function. +.SH SEE ALSO +.BR PMAPI (3), +.BR pmGetConfig (3), +.BR pmInDomStr (3), +.BR pmLookupDesc (3), +.BR pcp.conf (5) +and +.BR pcp.env (5). diff --git a/man/man3/pmiend.3 b/man/man3/pmiend.3 new file mode 100644 index 0000000..0c5d179 --- /dev/null +++ b/man/man3/pmiend.3 @@ -0,0 +1,59 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2010 Ken McDonell. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMIEND 3 "" "Performance Co-Pilot" +.SH NAME +\f3pmiEnd\f1 \- finish up a LOGIMPORT archive +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.br +#include <pcp/impl.h> +.br +#include <pcp/import.h> +.sp +int pmiEnd(void); +.sp +cc ... \-lpcp_import \-lpcp +.ft 1 +.SH "Perl SYNOPSIS" +.ft 3 +use PCP::LogImport; +.sp +pmiEnd(); +.ft 1 +.SH DESCRIPTION +As part of the Performance Co-Pilot Log Import API (see +.BR LOGIMPORT (3)), +.B pmiEnd +closes the current context, forcing the trailer records +to be written to the PCP archive files, and then these files are +closed. +.PP +In normal operations, an application would include a call +to +.B pmiEnd +at the end of processing for each context created with a call +to +.BR pmiStart (3). +.SH DIAGNOSTICS +.B pmiEnd +returns zero on success else a negative value that can be turned into an +error message by calling +.BR pmiErrStr (3). +.SH SEE ALSO +.BR LOGIMPORT (3) +and +.BR pmiStart (3). diff --git a/man/man3/pmierrstr.3 b/man/man3/pmierrstr.3 new file mode 100644 index 0000000..f41351c --- /dev/null +++ b/man/man3/pmierrstr.3 @@ -0,0 +1,78 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2012 Red Hat. +.\" Copyright (c) 2010 Ken McDonell. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMIERRSTR 3 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmiErrStr\f1 \- convert a LOGIMPORT error code into a string +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.br +#include <pcp/import.h> +.sp +const char *pmiErrStr(int \fIcode\fP); +.br +char *pmiErrStr_r(int \fIcode\fP, char \fIbuf\fP, int \fIbuflen\fP); +.sp +cc ... \-lpcp_import \-lpcp +.ft 1 +.SH "Perl SYNOPSIS" +.ft 3 +use PCP::LogImport; +.sp +pmiErrStr($\fIcode\fP); +.ft 1 +.SH DESCRIPTION +As part of the Performance Co-Pilot Log Import API (see +.BR LOGIMPORT (3)), +.B pmiErrStr +translates error codes returned from the other routines +in the Log Import library into printable error messages. +.PP +.I code +would normally have a negative value. +As a special case, if +.I code +is \-1 then the error code returned from the last routine +called in the LOGIMPORT library for this context will be +used. +.PP +The +.B pmiErrStr_r +function does the same, but stores the result in a user-supplied buffer +.I buf +of length +.IR buflen , +which should have room for at least +.B PMI_MAXERRMSGLEN +bytes. +.PP +The set of possible error codes and messages is all those defined +by +.BR pmErrStr (3) +and +.BR PCPIntro (3), +plus the additonal ones defined in +.B <pcp/import.h> +with error code names of the form +.BR PMI_ERR_.... +.SH DIAGNOSTICS +None. +.SH SEE ALSO +.BR LOGIMPORT (3), +.BR PCPIntro (3) +and +.BR pmErrStr (3). diff --git a/man/man3/pmigethandle.3 b/man/man3/pmigethandle.3 new file mode 100644 index 0000000..b7c6cd2 --- /dev/null +++ b/man/man3/pmigethandle.3 @@ -0,0 +1,81 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2010 Ken McDonell. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMIGETHANDLE3 "" "Performance Co-Pilot" +.SH NAME +\f3pmiGetHandle\f1 \- define a handle for a metric-instance pair +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.br +#include <pcp/impl.h> +.br +#include <pcp/import.h> +.sp +int pmiGetHandle(const char *\fIname\fP, const char *\fIinstance\fP); +.sp +cc ... \-lpcp_import \-lpcp +.ft 1 +.SH "Perl SYNOPSIS" +.ft 3 +use PCP::LogImport; +.sp +$\fIhandle\fP = pmiGetHandle($\fIname\fP, $\fIinstance\fP); +.ft 1 +.SH DESCRIPTION +As part of the Performance Co-Pilot Log Import API (see +.BR LOGIMPORT (3)), +.B pmiGetHandle +creates a handle for a given +metric and instance. The handle is returned as the value from the +.B pmiGetHandle +call and can be used in subsequent calls to +.BR pmiPutValueHandle (3). +.PP +The metric's +.I name +should match one defined earlier in a call to +.BR pmiAddMetric (3). +.PP +For singular metrics (those defined with an instance domain of +.BR PM_INDOM_NULL ), +the +.I instance +should be NULL or an empty string, otherwise +.I instance +should match the name of an instance defined earlier in a call +to +.BR pmiAddInstance (3) +for the metric's instance domain. +.PP +When combined with +.BR pmiPutValueHandle (3), +the use of handles provide a performance improvement over the +alternative lookup for a metric name and an instance name for +each data value that is required for +.BR pmiPutValue (3). +.SH DIAGNOSTICS +On failure +.B pmiGetHandle +returns a negative value that can be turned into an +error message by calling +.BR pmiErrStr (3). +.SH SEE ALSO +.BR LOGIMPORT (3), +.BR pmiAddInstance (3), +.BR pmiAddMetric (3), +.BR pmiErrStr (3) +and +.BR pmiPutValueHandle (3). diff --git a/man/man3/pmindomstr.3 b/man/man3/pmindomstr.3 new file mode 100644 index 0000000..b0c8135 --- /dev/null +++ b/man/man3/pmindomstr.3 @@ -0,0 +1,113 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000-2004 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMINDOMSTR 3 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmInDomStr\f1, +\f3pmInDomStr_r\f1 \- convert a performance metric instance domain identifier into a string +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.sp +const char *pmInDomStr(pmInDom \fIindom\fP); +.br +char *pmInDomStr_r(pmInDom \fIindom\fP, char *\fIbuf\fP, int \fIbuflen\fP); +.sp +cc ... \-lpcp +.ft 1 +.SH DESCRIPTION +.de CW +.ie t \f(CW\\$1\f1\\$2 +.el \fI\\$1\f1\\$2 +.. +For use in error and diagnostic messages, +.B pmInDomStr +return a 'human readable' version of +the specified instance domain identifier. +The +.B pmInDomStr_r +function does the same, but stores the result in a user-supplied buffer +.I buf +of length +.IR buflen , +which should have room for at least 20 bytes. +.PP +The value for the instance domain +.I indom +is typically extracted from a +.CW pmDesc +structure, following a call to +.BR pmLookupDesc (3) +for a particular performance metric. +.PP +Internally, an instance domain identifier is +encoded as follows; +.PP +.ft CW +.nf +.in +0.5i +typedef struct { + int pad:2; + unsigned int domain:8; /* the administrative PMD */ + unsigned int serial:22; /* unique within PMD */ +} __pmInDom_int; +.in +.fi +.ft 1 +.PP +.B pmInDomStr +returns a string with each of the +.CW domain +and +.CW serial +subfields appearing as decimal numbers, separated by periods. +.PP +The string value returned by +.B pmInDomStr +is held in a single static buffer, so the returned value is +only valid until the next call to +.BR pmInDomStr . +.SH NOTES +.B pmInDomStr +returns a pointer to a static buffer and hence is not thread-safe. +Multi-threaded applications should use +.B pmInDomStr_r +instead. +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.I /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). +Values for these variables may be obtained programmatically +using the +.BR pmGetConfig (3) +function. +.SH SEE ALSO +.BR PMAPI (3), +.BR pmGetConfig (3), +.BR pmIDStr (3), +.BR pmLookupDesc (3), +.BR pcp.conf (5) +and +.BR pcp.env (5). diff --git a/man/man3/pmiputresult.3 b/man/man3/pmiputresult.3 new file mode 100644 index 0000000..a73155c --- /dev/null +++ b/man/man3/pmiputresult.3 @@ -0,0 +1,82 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2010 Ken McDonell. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMIPUTRESULT 3 "" "Performance Co-Pilot" +.SH NAME +\f3pmiPutResult\f1 \- add a data record to a LOGIMPORT archive +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.br +#include <pcp/impl.h> +.br +#include <pcp/import.h> +.sp +int pmiPutResult(const pmResult *\fIresult\fP); +.sp +cc ... \-lpcp_import \-lpcp +.ft 1 +.SH DESCRIPTION +As part of the Performance Co-Pilot Log Import API (see +.BR LOGIMPORT (3)), +.B pmiPutResult +provides an interface for developers familiar with the internal +PCP data structures to create output archives directly. +.PP +By building the +.B pmResult +data structure directly, then calling +.B pmiPutResult +the developer avoids calls to +.BR pmiPutValue (3) +and/or +.BR pmiPutValueHandle (3) +followed by a call to +.BR pmiWrite (3) +for each record written to the archive. +.PP +Any metrics and instances appearing in the +.I result +must have been defined by prior calls to +.BR pmiAddMetric (3) +and +.BR pmiAddInstance (3). +.PP +.B pmiPutResult +will arrange for any new metadata (metrics and/or instance domain changes) +covered by +.I result +to be also written to the PCP archive. +.PP +Because of the complexity of the +.B pmResult +data structure, this routine is not available in the Perl +interface to the LOGIMPORT services. +.SH DIAGNOSTICS +.B pmiPutResult +returns zero on success else a negative value that can be turned into an +error message by calling +.BR pmiErrStr (3). +.SH SEE ALSO +.BR LOGIMPORT (3), +.BR PMAPI (3), +.BR pmiAddInstance (3), +.BR pmiAddMetric (3), +.BR pmiErrStr (3), +.BR pmiPutValue (3), +.BR pmiPutValueHandle (3), +.BR pmiSetTimezone (3) +and +.BR pmiWrite (3). diff --git a/man/man3/pmiputvalue.3 b/man/man3/pmiputvalue.3 new file mode 100644 index 0000000..4ab41f6 --- /dev/null +++ b/man/man3/pmiputvalue.3 @@ -0,0 +1,95 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2010 Ken McDonell. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMIPUTVALUE 3 "" "Performance Co-Pilot" +.SH NAME +\f3pmiPutValue\f1 \- add a value for a metric-instance pair +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.br +#include <pcp/impl.h> +.br +#include <pcp/import.h> +.sp +.ad l +.hy 0 +.in +8n +.ti -8n +int pmiPutValue(const char *\fIname\fP, const char *\fIinstance\fP, const\ char\ *\fIvalue\fP); +.sp +.in +.hy +.ad +cc ... \-lpcp_import \-lpcp +.ft 1 +.SH "Perl SYNOPSIS" +.ft 3 +use PCP::LogImport; +.sp +pmiPutValue($\fIname\fP, $\fIinstance\fP, $\fIvalue\fP); +.ft 1 +.SH DESCRIPTION +As part of the Performance Co-Pilot Log Import API (see +.BR LOGIMPORT (3)), +.B pmiPutValue +adds a single value to the current output record for a given +metric and instance. +.PP +The metric's +.I name +should match one defined earlier in a call to +.BR pmiAddMetric (3). +.PP +For singular metrics (those defined with an instance domain of +.BR PM_INDOM_NULL ), +the +.I instance +should be NULL or an empty string, otherwise +.I instance +should match the name of an instance defined earlier in a call +to +.BR pmiAddInstance (3) +for the metric's instance domain. +.PP +The +.I value +should be in a format consistent with the metric's type as +defined in the call to +.BR pmiAddMetric (3). +.PP +No data will be written until +.BR pmiWrite (3) +is called, so multiple calls to +.B pmiPutValue +or +.BR pmiPutValueHandle (3) +are typically used to accumulate data values for several +metric-instance pairs before calling +.BR pmiWrite (3). +.SH DIAGNOSTICS +.B pmiPutValue +returns zero on success else a negative value that can be turned into an +error message by calling +.BR pmiErrStr (3). +.SH SEE ALSO +.BR LOGIMPORT (3), +.BR pmiAddInstance (3), +.BR pmiAddMetric (3), +.BR pmiErrStr (3), +.BR pmiPutResult (3), +.BR pmiPutValueHandle (3) +and +.BR pmiWrite (3). diff --git a/man/man3/pmiputvaluehandle.3 b/man/man3/pmiputvaluehandle.3 new file mode 100644 index 0000000..d9924a5 --- /dev/null +++ b/man/man3/pmiputvaluehandle.3 @@ -0,0 +1,74 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2010 Ken McDonell. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMIPUTVALUEHANDLE 3 "" "Performance Co-Pilot" +.SH NAME +\f3pmiPutValueHandle\f1 \- add a value for a metric-instance pair via a handle +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.br +#include <pcp/impl.h> +.br +#include <pcp/import.h> +.sp +int pmiPutValueHandle(int \fIhandle\fP, const char *\fIvalue\fP); +.sp +cc ... \-lpcp_import \-lpcp +.ft 1 +.SH "Perl SYNOPSIS" +.ft 3 +use PCP::LogImport; +.sp +pmiPutValueHandle($\fIhandle\fP, $\fIvalue\fP); +.ft 1 +.SH DESCRIPTION +As part of the Performance Co-Pilot Log Import API (see +.BR LOGIMPORT (3)), +.B pmiPutValueHandle +adds a single value to the current output record for a given +metric and instance, using the +.I handle +defined by an earlier call to +.BR pmiGetHandle (3). +.PP +The +.I value +should be in a format consistent with the metric's type as +defined in the call to +.BR pmiAddMetric (3). +.PP +No data will be written until +.BR pmiWrite (3) +is called, so multiple calls to +.B pmiPutValueHandle +or +.BR pmiPutValue (3) +are typically used to accumulate data values for several +metric-instance pairs before calling +.BR pmiWrite (3). +.SH DIAGNOSTICS +.B pmiPutValueHandle +returns zero on success else a negative value that can be turned into an +error message by calling +.BR pmiErrStr (3). +.SH SEE ALSO +.BR LOGIMPORT (3), +.BR pmiErrStr (3), +.BR pmiGetHandle (3), +.BR pmiPutResult (3), +.BR pmiPutValue (3) +and +.BR pmiWrite (3). diff --git a/man/man3/pmisethostname.3 b/man/man3/pmisethostname.3 new file mode 100644 index 0000000..bfd4ba1 --- /dev/null +++ b/man/man3/pmisethostname.3 @@ -0,0 +1,57 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2010 Ken McDonell. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMISETHOSTNAME 3 "" "Performance Co-Pilot" +.SH NAME +\f3pmiSetHostname\f1 \- set the source host name for a LOGIMPORT archive +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.br +#include <pcp/impl.h> +.br +#include <pcp/import.h> +.sp +int pmiSetHostname(const char *\fIvalue\fP); +.sp +cc ... \-lpcp_import \-lpcp +.ft 1 +.SH "Perl SYNOPSIS" +.ft 3 +use PCP::LogImport; +.sp +pmiSetHostname($\fIvalue\fP); +.ft 1 +.SH DESCRIPTION +As part of the Performance Co-Pilot Log Import API (see +.BR LOGIMPORT (3)), +.B pmiSetHostname +sets the source hostname in the current context to be +.IR value . +.PP +In the absence of a call to +.B pmiSetHostname +the source hostname defaults to the hostname of the localhost. +.SH DIAGNOSTICS +.B pmiSetHostname +returns zero on success else a negative value that can be turned into an +error message by calling +.BR pmiErrStr (3). +.SH SEE ALSO +.BR LOGIMPORT (3), +.BR pmiErrStr (3), +.BR pmiSetTimezone (3) +and +.BR pmiStart (3). diff --git a/man/man3/pmisettimezone.3 b/man/man3/pmisettimezone.3 new file mode 100644 index 0000000..a4186aa --- /dev/null +++ b/man/man3/pmisettimezone.3 @@ -0,0 +1,57 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2010 Ken McDonell. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMISETTIMEZONE 3 "" "Performance Co-Pilot" +.SH NAME +\f3pmiSetTimezone\f1 \- set the source timezone for a LOGIMPORT archive +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.br +#include <pcp/impl.h> +.br +#include <pcp/import.h> +.sp +int pmiSetTimezone(const char *\fIvalue\fP); +.sp +cc ... \-lpcp_import \-lpcp +.ft 1 +.SH "Perl SYNOPSIS" +.ft 3 +use PCP::LogImport; +.sp +pmiSetTimezone($\fIvalue\fP); +.ft 1 +.SH DESCRIPTION +As part of the Performance Co-Pilot Log Import API (see +.BR LOGIMPORT (3)), +.B pmiSetTimezone +sets the source timezone in the current context to be +.IR value . +.PP +In the absence of a call to +.B pmiSetTimezone +the source timezone defaults to the timezone of the localhost. +.SH DIAGNOSTICS +.B pmiSetTimezone +returns zero on success else a negative value that can be turned into an +error message by calling +.BR pmiErrStr (3). +.SH SEE ALSO +.BR LOGIMPORT (3), +.BR pmiErrStr (3), +.BR pmiSetHostname (3) +and +.BR pmiStart (3). diff --git a/man/man3/pmistart.3 b/man/man3/pmistart.3 new file mode 100644 index 0000000..fcb66fb --- /dev/null +++ b/man/man3/pmistart.3 @@ -0,0 +1,139 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2010 Ken McDonell. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMISTART 3 "" "Performance Co-Pilot" +.SH NAME +\f3pmiStart\f1 \- establish a new LOGIMPORT context +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.br +#include <pcp/impl.h> +.br +#include <pcp/import.h> +.sp +int pmiStart(const char *\fIarchive\fP, int \fIinherit\fP); +.sp +cc ... \-lpcp_import \-lpcp +.ft 1 +.SH "Perl SYNOPSIS" +.ft 3 +use PCP::LogImport; +.sp +pmiStart($\fIarchive\fP, $\fIinherit\fP); +.ft 1 +.SH DESCRIPTION +As part of the Performance Co-Pilot Log Import API (see +.BR LOGIMPORT (3)), +.B pmiStart +creates a new context. Each context maintains the following +state and metadata: +.IP \(bu 3n +The base name (\c +.IR archive ) +for the physical files +that constitute the output PCP archive. +.IP \(bu 3n +The source hostname for the data that will be written to the +PCP archive. Defaults to the hostname of the localhost, but can be set using +.BR pmiSetHostname (3). +.IP \(bu 3n +The source timezone for the +PCP archive. Defaults to the timezone of the localhost, but can be set using +.BR pmiSetTimezone (3). +.IP \(bu 3n +Metrics and instance domains, as defined by +.BR pmiAddMetric (3). +.IP \(bu 3n +Instances for each instance domain, as defined by +.BR pmiAddInstance (3). +.IP \(bu 3n +Handles as defined by +.BR pmiGetHandle (3). +Each handle is a metric-instance pair, and each metric-instance pair +may have an associated value in each record written to the output +PCP archive. +.IP \(bu 3n +An optional set of data values for one or more metric-instance pairs +(ready for the next record to be written +to the output PCP archive) as defined +by calls to +.BR pmPutValue (3) +or +.BR pmPutValuehandle (3). +.PP +If +.I inherit +is true, then the new context will inherit any and all +metadata (metrics, instance domains, instances and handles) from the current +context, otherwise the new context is created with no metadata. +The basename for the output PCP archive, the source hostname, the +source timezone and any data values from the current context are +.B not +inherited. +If this is the first call to +.B pmiStart +the metadata will be empty +independent of the value of +.IR inherit . +.PP +Since no physical files for the output PCP archive +will be created until the first call to +.BR pmiWrite (3) +or +.BR pmiPutRecord(3), +.I archive +could be NULL to create a +convenience context that is populated with metadata to be +inherited by subsequent contexts. +.PP +The return value is a context identifier that +could be used in a subsequent call to +.BR pmUseContext (3) +and the +new context becomes the current context which +persists for all subsequent calls up to either another +.B pmiStart +call or a call to +.BR pmiUseContext (3) +or a call to +.BR pmiEnd (3). +.SH DIAGNOSTICS +It is an error if the physical files +\fIarchive\fR.\fB0\fR and/or +\fIarchive\fR.\fBindex\fR and/or +\fIarchive\fR.\fBmeta\fR already exist, but this is not discovered +until the first attempt is made to output some data by calling +.BR pmiWrite (3) +or +.BR pmiPutRecord(3), +so +.B pmiStart +always returns a positive context identifier. +.SH SEE ALSO +.BR LOGIMPORT (3), +.BR pmiAddInstance (3), +.BR pmiAddMetric (3), +.BR pmiEnd (3), +.BR pmiErrStr (3), +.BR pmiGetHandle (3), +.BR pmiPutResult (3), +.BR pmiPutValue (3), +.BR pmiPutValueHandle (3), +.BR pmiSetHostname (3), +.BR pmiSetTimezone (3), +.BR pmiUseContext (3) +and +.BR pmiWrite (3). diff --git a/man/man3/pmiunits.3 b/man/man3/pmiunits.3 new file mode 100644 index 0000000..b58fbea --- /dev/null +++ b/man/man3/pmiunits.3 @@ -0,0 +1,92 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2012 Red Hat. +.\" Copyright (c) 2010 Ken McDonell. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMIUNITS 3 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmiUnits\f1, +\f3pmiID\f1, +\f3pmiInDom\f1 \- construct core metric data structures +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.br +#include <pcp/import.h> +.sp +.ad l +.hy 0 +.in +8n +.ti -8n +pmID +pmiID(int \fIdomain\fP, int \fIcluster\fP, int \fIitem\fP); +.ti -8n +pmInDom +pmiInDom(int \fIdomain\fP, int \fIserial\fP); +.ti -8n +pmUnits +pmiUnits(int \fIdimSpace\fP, int \fIdimTime\fP, int \fIdimCount\fP, int\ \fIscaleSpace\fP, int\ \fIscaleTime\fP, int\ \fIscaleCount\fP); +.sp +.in +.hy +.ad +cc ... \-lpcp_import \-lpcp +.ft 1 +.SH "Perl SYNOPSIS" +.ft 3 +use PCP::LogImport; +.sp +.ad l +.hy 0 +.in +8n +.ti -8n +$pmid = pmiID($\fIdomain\fP, $\fIcluster\fP, $\fIitem\fP); +.ti -8n +$indom = pmiInDom($\fIdomain\fP, $\fIserial\fP); +.ti -8n +$units = pmiUnits($\fIdimSpace\fP, $\fIdimTime\fP, $\fIdimCount\fP, $\fIscaleSpace\fP, $\fIscaleTime\fP, $\fIscaleCount\fP); +.sp +.in +.hy +.ad +.ft 1 +.SH DESCRIPTION +As part of the Performance Co-Pilot Log Import API (see +.BR LOGIMPORT (3)), +these routines provide +convenience methods (especially for script use) for constructing +.BR pmID , +.B pmInDom +and +.B pmUnits +structures respectively, to be used in subsequent calls to +.BR pmiAddMetric (3) +and +.BR pmiAddInstance (3). +.PP +Refer to +.BR pmLookupDesc (3) +for a complete description of the values and semantics of the +components of a +.B pmUnits +structure, and hence the valid argument values for +.BR pmiUnits . +.SH DIAGNOSTICS +None. +.SH SEE ALSO +.BR LOGIMPORT (3), +.BR pmiAddMetric (3), +.BR pmiAddInstance (3) +and +.BR pmLookupDesc (3). diff --git a/man/man3/pmiusecontext.3 b/man/man3/pmiusecontext.3 new file mode 100644 index 0000000..b85c233 --- /dev/null +++ b/man/man3/pmiusecontext.3 @@ -0,0 +1,62 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2010 Ken McDonell. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMIUSECONTEXT 3 "" "Performance Co-Pilot" +.SH NAME +\f3pmiUseContext\f1 \- change LOGIMPORT context +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.br +#include <pcp/impl.h> +.br +#include <pcp/import.h> +.sp +int pmiUseContext(int \fIcontext\fP); +.sp +cc ... \-lpcp_import \-lpcp +.ft 1 +.SH "Perl SYNOPSIS" +.ft 3 +use PCP::LogImport; +.sp +pmiUseContext($\fIcontext\fP); +.ft 1 +.SH DESCRIPTION +As part of the Performance Co-Pilot Log Import API (see +.BR LOGIMPORT (3)), +.B pmiUseContext +may be used by applications wishing to generate more than +one PCP archive concurrently. +.PP +The +.I context +argument is a value returned from a previous call to +.BR pmStart (3) +and on successful return from +.BR pmiUseContext , +the current context will have been changed to the one identified +by +.IR context . +.SH DIAGNOSTICS +.B pmiUseContext +returns zero on success else a negative value that can be turned into an +error message by calling +.BR pmiErrStr (3). +.SH SEE ALSO +.BR LOGIMPORT (3), +.BR pmiErrStr (3) +and +.BR pmiStart (3). diff --git a/man/man3/pmiwrite.3 b/man/man3/pmiwrite.3 new file mode 100644 index 0000000..dac6ded --- /dev/null +++ b/man/man3/pmiwrite.3 @@ -0,0 +1,71 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2010 Ken McDonell. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMIWRITE 3 "" "Performance Co-Pilot" +.SH NAME +\f3pmiWrite\f1 \- flush data to a LOGIMPORT archive +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.br +#include <pcp/impl.h> +.br +#include <pcp/import.h> +.sp +int pmiWrite(int \fIsec\fP, int \fIusec\fP); +.sp +cc ... \-lpcp_import \-lpcp +.ft 1 +.SH "Perl SYNOPSIS" +.ft 3 +use PCP::LogImport; +.sp +pmiWrite($\fIsec\fP, $\fIusec\fP); +.ft 1 +.SH DESCRIPTION +As part of the Performance Co-Pilot Log Import API (see +.BR LOGIMPORT (3)), +.B pmiWrite +forces accumulated data values out to the PCP archive. +.PP +The data values and associated metadata have previously been +built up using calls to +.BR pmiAddMetric (3), +.BR pmiAddInstance (3), +.BR pmiPutValue (3) +and +.BR pmiPutValueHandle (3). +.PP +The current set of data values and any new metadata is written to the archive with +a timestamp of +.I sec +and +.I usec +in the source timezone of the archive, see +.BR pmiSetTimezone (3). +.SH DIAGNOSTICS +.B pmiWrite +returns zero on success else a negative value that can be turned into an +error message by calling +.BR pmiErrStr (3). +.SH SEE ALSO +.BR LOGIMPORT (3), +.BR pmiAddInstance (3), +.BR pmiAddMetric (3), +.BR pmiErrStr (3), +.BR pmiPutValue (3), +.BR pmiPutValueHandle (3) +and +.BR pmiSetTimezone (3). diff --git a/man/man3/pmloadasciinamespace.3 b/man/man3/pmloadasciinamespace.3 new file mode 100644 index 0000000..a2778ed --- /dev/null +++ b/man/man3/pmloadasciinamespace.3 @@ -0,0 +1,117 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMLOADASCIINAMESPACE 3 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmLoadASCIINameSpace\f1 \- establish a local PMNS for an application +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.sp +int pmLoadASCIINameSpace(const char *\fIfilename\fP, int \fIdupok\fP); +.sp +cc ... \-lpcp +.ft 1 +.SH DESCRIPTION +If the application wants to force using a local Performance Metrics +Name Space (PMNS) instead +of a distributed PMNS then it must load the PMNS using +.B pmLoadASCIINameSpace +or +.BR pmLoadNameSpace (3). +If the application wants to use a distributed PMNS, then it should NOT +make a call to load the PMNS explicitly. +.PP +.B pmLoadASCIINameSpace +is a variant of +.BR pmLoadNameSpace (3) +in which the +.I dupok +argument may be used to control the handling of multiple names +in the PMNS that may be associated with a single Performance Metric +Identifier (PMID). A value of 0 disallows duplicates, any other value allows +duplicates. +.PP +The +.I filename +argument designates the PMNS of interest. +For applications not requiring a tailored PMNS, +the special value +.B PM_NS_DEFAULT +may be +used for +.IR filename , +to force the default local PMNS to be loaded. +.PP +The default local PMNS is found in the file +.I $PCP_VAR_DIR/pmns/root +unless the environment variable +.B PMNS_DEFAULT +is set, in which case the value is assumed to be the pathname +to the file containing the default local PMNS. +.PP +.B pmLoadASCIINameSpace +returns zero on success. +.SH FILES +.IP \f2$PCP_VAR_DIR/pmns/root\f1 2.5i +the default local PMNS, when the environment variable +.B PMNS_DEFAULT +is unset +.RE +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.I /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). +Values for these variables may be obtained programmatically +using the +.IR pmGetConfig (3) +function. +.SH SEE ALSO +.BR PMAPI (3), +.BR pmGetConfig (3), +.BR pmLoadNameSpace (3), +.BR pmTrimNameSpace (3), +.BR pcp.conf (5), +.BR pcp.env (5) +and +.BR pmns (5). +.SH DIAGNOSTICS +Syntax and other errors in the parsing of the PMNS are reported +on +.I stderr +with a message of the form ``Error Parsing ASCII PMNS: ...''. +.PP +.B PM_ERR_DUPPMNS +.IP +It is an error to try to load more than one PMNS, or to call +either +.B pmLoadASCIINameSpace +and/or +.BR pmLoadNameSpace (3) +more than once. +.PP +.B PM_ERR_PMNS +.IP +Syntax error in an ASCII format PMNS. diff --git a/man/man3/pmloadderivedconfig.3 b/man/man3/pmloadderivedconfig.3 new file mode 100644 index 0000000..062be54 --- /dev/null +++ b/man/man3/pmloadderivedconfig.3 @@ -0,0 +1,68 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2009 Ken McDonell. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMLOADDERIVEDCONFIG 3 "" "Performance Co-Pilot" +.SH NAME +\f3pmLoadDerivedConfig\f1 \- load derived metric definitions from a file +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.sp +int pmLoadDerivedConfig(char *\fIfname\fP); +.sp +cc ... \-lpcp +.ft 1 +.SH DESCRIPTION +.PP +Each line of the file +.I fname +is either a comment line (with a ``#'' in the first position of the line) +or the declaration of a derived performance metric, specified as: +.IP * 2n +the name of the derived metric, using the same ``dot notation'' syntax +that is used for PCP performance metrics, see +.BR PCPIntro (1) +and +.BR pmns (5). +.IP * 2n +an equals sign (``='') +.IP * 2n +a valid expression for a derived metric, as described in +.BR pmRegisterDerived (3). +.PP +White space is ignored in the lines. +.PP +For each line containing a derived metric definition, +.BR pmRegisterDerived (3) +is called to register the new derived metric. +.PP +The result from +.B pmLoadDerivedConfig +will be the number of derived metrics loaded from +.I fname +else a value less than zero in the case of an error. +.SH EXAMPLE +.nf +# sample derived metric definitions +bad_in_pkts = network.interface.in.errors + network.interface.in.drops +# note the following would need to be on a single line ... +disk.dev.read_pct = 100 * delta(disk.dev.read) / + (delta(disk.dev.read) + delta(disk.dev.write)) +.fi +.SH SEE ALSO +.BR PCPIntro (1), +.BR PMAPI (3) +and +.BR pmRegisterDerived (3). diff --git a/man/man3/pmloadnamespace.3 b/man/man3/pmloadnamespace.3 new file mode 100644 index 0000000..3a3f853 --- /dev/null +++ b/man/man3/pmloadnamespace.3 @@ -0,0 +1,119 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMLOADNAMESPACE 3 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmLoadNameSpace\f1 \- load a local PMNS for an application +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.sp +int pmLoadNameSpace(const char *\fIfilename\fP); +.sp +cc ... \-lpcp +.ft 1 +.SH DESCRIPTION +If the application wants to force using a local Performance Metrics +Name Space (PMNS) instead of a distributed PMNS then it +must load the PMNS using +.B pmLoadNameSpace +or +.BR pmLoadASCIINameSpace (3). +If the application is to use a distributed PMNS, then it should NOT +make a call to load the PMNS explicitly. +.PP +The +.I filename +argument designates the PMNS of interest. +For applications not requiring a tailored PMNS, +the special value +.B PM_NS_DEFAULT +may be +used for +.IR filename , +to force the default local PMNS to be loaded. +.PP +The default local PMNS is found in the file +.I $PCP_VAR_DIR/pmns/root +unless the environment variable +.B PMNS_DEFAULT +is set, in which case the value is assumed to be the pathname +to the file containing the default local PMNS. +.PP +Externally a PMNS is stored in an ASCII format as +described in +.BR pmns (5). +.PP +By default, +multiple names in the PMNS are not allowed to be +associated with a single Performance +Metrics Identifier (PMID). +.BR pmLoadASCIINameSpace (3) +provides an alternative interface with user-defined control +over the processing of duplicate PMIDs in the PMNS. +.PP +.B pmLoadNameSpace +returns zero on success. +.SH FILES +.IP \f2$PCP_VAR_DIR/pmns/root\f1 2.5i +the default local PMNS, when the environment variable +.B PMNS_DEFAULT +is unset +.RE +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.I /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). +Values for these variables may be obtained programmatically +using the +.IR pmGetConfig (3) +function. +.SH SEE ALSO +.BR PMAPI (3), +.BR pmGetConfig (3), +.BR pmLoadASCIINameSpace (3), +.BR pmTrimNameSpace (3), +.BR pcp.conf (5), +.BR pcp.env (5) +and +.BR pmns (5). +.SH DIAGNOSTICS +Syntax and other errors in the parsing of the PMNS are reported +on +.I stderr +with a message of the form ``Error Parsing ASCII PMNS: ...''. +.PP +.B PM_ERR_DUPPMNS +.IP +It is an error to try and load more than one PMNS, or to call +either +.B pmLoadNameSpace +and/or +.BR pmLoadASCIINameSpace (3) +more than once. +.PP +.B PM_ERR_PMNS +.IP +Syntax error in the PMNS file. diff --git a/man/man3/pmlocalpmda.3 b/man/man3/pmlocalpmda.3 new file mode 100644 index 0000000..2fc3085 --- /dev/null +++ b/man/man3/pmlocalpmda.3 @@ -0,0 +1,155 @@ +'\"macro stdmacro +.TH PMLOCALPMDA 3 "" "Performance Co-Pilot" +.SH NAME +\f3__pmLocalPMDA\f1 \- change the table of DSO PMDAs for PM_CONTEXT_LOCAL contexts +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.br +#include <pcp/impl.h> +.sp +.ad l +.hy 0 +.in +8n +.ti -8n +int __pmLocalPMDA(int \fIop\fP, int \fIdomain\fP, const char *\fIname\fP, const\ char\ *\fIinit\fP); +.sp +.in +.hy +.ad +cc ... \-lpcp +.ft 1 +.SH DESCRIPTION +PCP contexts of type +.B PM_CONTEXT_LOCAL +are used by clients that wish to fetch metrics directly from one or more PMDAs on +the local host without involving +.BR pmcd (1). +A PMDA that is to be used in this way must have been built as a +Dynamic Shared Object (DSO). +.P +Historically the table of PMDAs available for use with +.B PM_CONTEXT_LOCAL +was hardcoded to the following: +.IP * 2n +The PMDA (or PMDAs) that export the operating system performance data +and data about process activity. +.PD 0 +.IP * +The +.B mmv +PMDA. +.IP * +The +.B sample +PMDA provided +.B $PCP_LITE_SAMPLE +or +.B $PMDA_LOCAL_SAMPLE +is set in the environment \- used mostly for QA and testing. +.PD +.PP +The initial table of PMDAs available for use with +.B PM_CONTEXT_LOCAL +is now generated dynamically from all those PMDAs that have been +installed as DSOs on the local host. +The one exception is the ``pmcd'' +PMDA which only operates correctly in the address space of a running +.BR pmcd (1) +process and so is not available to an application using a +.B PM_CONTEXT_LOCAL +context. +.PP +.B __pmLocalPMDA +provides a number of services to amend the table of PMDAs +available for use with +.BR PM_CONTEXT_LOCAL . +.P +The +.I op +argument specifies the what should be done and takes one of the following +values and actions: +.IP PM_LOCAL_ADD 16n +Append an entry to the table for the PMDA with a Performance Metrics Domain +(PMD) of +.IR domain , +the path to the DSO PMDA is given by +.I path +and the PMDA's initialization routine is +.IR init . +.IP PM_LOCAL_DEL +Removes all entries in the table where the +.I domain +matches, or the +.I path +matches. Setting the arguments +.I domain +to \-1 or +.I path +to +.B NULL +to force matching on the +.I other +argument. +The +.I init +argument is ignored. +.IP PM_LOCAL_CLEAR +Remove all entries from the table. All the other arguments are ignored +in this case. +.P +The +.IR domain , +.I name +and +.I init +arguments have similar syntax and semantics to the associated fields +in the +.BR pmcd (1) +configuration file. +The one difference is the +.I path +argument which is used by +.B __pmLocalPMDA +to find a likely looking DSO by searching in this order: +.B $PCP_PMDAS_DIR\c +/\c +.IR path , +.IR path , +.B $PCP_PMDAS_DIR\c +/\c +.I path\c +\&.\c +.I dso-suffix +and finally +.I path\c +\&.\c +.I dso-suffix +(\c +.I dso-suffix +is the local platform specific default file name suffix for a DSO, e.g. +.B so +for Linux, +.B dylib +for Mac OS X, +.B dll +for Windows, +etc.). +.SH "RETURN VALUE" +In most cases, +.B __pmLocalPMDA +returns 0 +to indicate success. +If +.I op +is invalid, then the return value is +.B PM_ERR_CONV +else if there is no matching table entry found for a +.B PM_LOCAL_DEL +operation, PM_ERR_INDOM is returned. +.SH SEE ALSO +.BR pmcd (1), +.BR PMAPI (3), +.BR pmNewContext (3) +and +.BR __pmSpecLocalPMDA (3). diff --git a/man/man3/pmlocaltime.3 b/man/man3/pmlocaltime.3 new file mode 100644 index 0000000..3239592 --- /dev/null +++ b/man/man3/pmlocaltime.3 @@ -0,0 +1,82 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMLOCALTIME 3 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmLocaltime\f1 \- convert the date and time for a reporting timezone +.SH "C SYNOPSIS" +.ft 3 +#include <time.h> +.br +#include <pcp/pmapi.h> +.sp +struct tm *pmLocaltime(const time_t *\fIclock\fP, struct tm *\fIresult\fP); +.sp +cc ... \-lpcp +.ft 1 +.SH DESCRIPTION +.B pmLocaltime +is very similar to +.BR localtime (3), +except the timezone used is the current ``reporting timezone'' (rather than the +default +.B TZ +environment variable scheme), and the result is returned into a +caller-declared buffer (rather than a private buffer). +.PP +Like +.BR localtime (3) +the time to be converted is passed via +.IR clock , +and +the +.I result +contains the components broken out in the elements of the +.I tm +struct. +.PP +.B pmLocaltime +returns +.I result +as the value of the function. +.PP +The default current reporting timezone is as defined by the +.B TZ +environment variable, so +.B pmLocaltime +and +.BR localtime (3) +will initially produce a similar encoding of the date and time. +.PP +Use +.BR pmNewZone (3), +.BR pmNewContextZone (3) +or +.BR pmUseZone (3) +to establish a new current reporting timezone that will affect +.B pmLocaltime +but not +.BR localtime (3). +.SH SEE ALSO +.BR localtime (3), +.BR PMAPI (3), +.BR pmCtime (3), +.BR pmGetConfig (3), +.BR pmNewContextZone (3), +.BR pmNewZone (3), +.BR pmUseZone (3), +.BR pcp.conf (5) +and +.BR pcp.env (5). diff --git a/man/man3/pmlookupdesc.3 b/man/man3/pmlookupdesc.3 new file mode 100644 index 0000000..926ea07 --- /dev/null +++ b/man/man3/pmlookupdesc.3 @@ -0,0 +1,239 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.\" add in the -me strings for super and subscripts +.ie n \{\ +. ds [ \u\x'-0.25v' +. ds ] \d +. ds { \d\x'0.25v' +. ds } \u +.\} +.el \{\ +. ds [ \v'-0.4m'\x'-0.2m'\s-3 +. ds ] \s0\v'0.4m' +. ds { \v'0.4m'\x'0.2m'\s-3 +. ds } \s0\v'-0.4m' +.\} +.TH PMLOOKUPDESC 3 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmLookupDesc\f1 \- obtain a description for a performance metric +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.sp +.nf +int pmLookupDesc(pmID \fIpmid\fP, pmDesc *\fIdesc\fP); +.fi +.sp +cc ... \-lpcp +.ft 1 +.SH DESCRIPTION +.de CW +.ie t \f(CW\\$1\f1\\$2 +.el \fI\\$1\f1\\$2 +.. +Given a Performance Metrics Identifier (PMID) as +.IR pmid , +fill in the given +.CW pmDesc +structure, pointed to by the parameter +.IR desc , +from the current +Performance Metrics Application Programming Interface (PMAPI) +context. +.PP +The +.CW pmDesc +structure provides all of the information required to describe and +manipulate a +performance metric via the +PMAPI, and has the following declaration. +.PP +.ft CW +.nf +.in +0.5i +/* 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; + +/* pmDesc.type -- data type of metric values */ +#define PM_TYPE_NOSUPPORT \-1 /* not impl. 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 */ + + +/* pmDesc.sem -- semantics/interpretation of metric values */ +#define PM_SEM_COUNTER 1 /* cumulative ctr (monotonic incr) */ +#define PM_SEM_INSTANT 3 /* instant. value continuous domain */ +#define PM_SEM_DISCRETE 4 /* instant. value discrete domain */ +.in +.fi +.ft 1 +.PP +The +.CW type +field in the +.CW pmDesc +describes various encodings (or formats) for a metric's value. +.PP +If a value is +counted in the underlying base instrumentation with less than 32 bits of +integer precision, it is the responsibility of the Performance Metrics +Domain Agent (PMDA) to promote the value to a 32-bit integer before it is +exported into the Performance Metrics Collection Subsystem (PMCS); +i.e. applications above the PMAPI never have to deal with 8-bit and 16-bit +counters. +.PP +If the value of a performance metric is of type +.BR PM_TYPE_AGGREGATE , +.BR PM_TYPE_AGGREGATE_STATIC, +.B PM_TYPE_EVENT +or +.BR PM_TYPE_STRING , +the interpretation of the value is unknown to the PMCS. +In these cases, the +application using the value, and the PMDA providing the value must have some +common understanding about how the value is structured and interpreted. +.PP +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. +The dimensionality is defined by a power, or index, in +each of 3 orthogonal dimensions, namely Space, Time and Count +(or Events, which are dimensionless). +For example I/O throughput might be represented as +.ti 1i +.CW "\0\0\0\0\0\0\0\0\0\0-1" +.ti 1i +.CW "Space.Time" +.br +while the +running total of system calls is +.CW "Count" , +memory allocation is +.CW Space +and average +service time is +.ti 1i +.CW "\0\0\0\0\0\0\0\0\0\0-1" +.ti 1i +.CW "Time.Count" +.br +In each dimension there are a number +of common scale values that may be used to better encode ranges that might +otherwise exhaust the precision of a 32-bit value. +This information is encoded +in the +.CW pmUnits +structure which is embedded in the +.CW pmDesc +structure. +.PP +.ft CW +.nf +.in +0.5i +/* + * Encoding for the units (dimensions Time and Space) 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 dimSpace:4; /* space dimension */ + int dimTime:4; /* time dimension */ + int dimCount:4; /* event dimension */ + int scaleSpace:4; /* one of PM_SPACE_* below */ + int scaleTime:4; /* one of PM_TIME_* below */ + int scaleCount:4; /* one of PM_COUNT_* below */ +} 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 */ +.in +.fi +.ft 1 +.PP +Special routines (e.g. \c +.BR pmExtractValue (3), +.BR pmConvScale (3)) +are provided to manipulate values in +conjunction with the +.CW pmUnits +structure that defines the dimension and scale of the values for a particular +performance metric. +.PP +Below the PMAPI, the information required to complete the +.CW pmDesc +structure, is fetched from the PMDAs, and in this way the format +and scale of performance metrics may change dynamically, as +the PMDAs and their underlying +instrumentation evolve with time. +In particular, when some metrics suddenly +become 64-bits long, or change their units from Mbytes to Gbytes, +well-written applications +using the services provided by the PMAPI will continue +to function correctly. +.SH SEE ALSO +.BR PMAPI (3), +.BR pmAtomStr (3), +.BR pmConvScale (3), +.BR pmExtractValue (3), +.BR pmGetConfig (3), +.BR pmTypesStr (3), +.BR pmUnitsStr (3), +.BR pcp.conf (5) +and +.BR pcp.env (5). +.SH DIAGNOSTICS +.IP \f3PM_ERR_PMID\f1 +The requested PMID is not known to the PMCS +.IP \f3PM_ERR_NOAGENT\f1 +The PMDA responsible for providing the metric is currently not available diff --git a/man/man3/pmlookupindom.3 b/man/man3/pmlookupindom.3 new file mode 100644 index 0000000..97a2137 --- /dev/null +++ b/man/man3/pmlookupindom.3 @@ -0,0 +1,77 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMLOOKUPINDOM 3 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmLookupInDom\f1 \- translate an instance name into an instance identifier +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.sp +.nf +int pmLookupInDom(pmInDom \fIindom\fP, const char *\fIname\fP); +.fi +.sp +cc ... \-lpcp +.ft 1 +.SH DESCRIPTION +.de CW +.ie t \f(CW\\$1\f1\\$2 +.el \fI\\$1\f1\\$2 +.. +For the instance domain +.IR indom , +in the current +Performance Metrics Application Programming Interface (PMAPI) +context, +locate the instance with the external identification given by +.IR name , +and return the internal instance identifier. +.PP +Only the leading +non-space characters of +.I name +will be used to identify the instance. +.PP +The value for the instance domain +.I indom +is typically extracted from a +.CW pmDesc +structure, following a call to +.BR pmLookupDesc (3) +for a particular performance metric. +.PP +.B pmLookupInDom +will return a positive instance identifier on success. +.SH SEE ALSO +.BR PMAPI (3), +.BR pmGetConfig (3), +.BR pmGetInDom (3), +.BR pmLookupDesc (3), +.BR pmLookupInDomArchive (3), +.BR pmNameInDom (3), +.BR pcp.conf (5) +and +.BR pcp.env (5). +.SH DIAGNOSTICS +.IP \f3PM_ERR_INDOM\f1 +.I indom +is not a valid instance domain identifier +.IP \f3PM_ERR_INST\f1 +The external instance +.I name +is not known for the instance domain +.I indom +in the current PMAPI context diff --git a/man/man3/pmlookupindomarchive.3 b/man/man3/pmlookupindomarchive.3 new file mode 100644 index 0000000..fa349dc --- /dev/null +++ b/man/man3/pmlookupindomarchive.3 @@ -0,0 +1,83 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMLOOKUPINDOMARCHIVE 3 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmLookupInDomArchive\f1 \- translate an instance name into an instance identifier +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.sp +int pmLookupInDomArchive(pmInDom \fIindom\fP, const char *\fIname\fP); +.sp +cc ... \-lpcp +.ft 1 +.SH DESCRIPTION +.de CW +.ie t \f(CW\\$1\f1\\$2 +.el \fI\\$1\f1\\$2 +.. +Provided the current +Performance Metrics Application Programming Interface (PMAPI) +context is associated with an archive log, +.B pmLookupInDomArchive +will scan the union of all the instance domain metadata +for the instance domain +.IR indom , +locate the first instance with the external identification given by +.IR name , +and return the internal instance identifier. +.PP +This routine is a specialized version of the more general PMAPI +routine +.BR pmLookupInDom . +.PP +Only the leading +non-space characters of +.I name +will be used to identify the instance. +.PP +The value for the instance domain +.I indom +is typically extracted from a +.CW pmDesc +structure, following a call to +.BR pmLookupDesc (3) +for a particular performance metric. +.PP +.B pmLookupInDomArchive +will return a positive instance identifier on success. +.SH SEE ALSO +.BR PMAPI (3), +.BR pmGetConfig (3), +.BR pmGetInDomArchive (3), +.BR pmLookupDesc (3), +.BR pmLookupInDom (3), +.BR pmNameInDomArchive (3), +.BR pcp.conf (5) +and +.BR pcp.env (5). +.SH DIAGNOSTICS +.IP \f3PM_ERR_NOTARCHIVE\f1 +the current PMAPI context is not associated with an archive log +.IP \f3PM_ERR_INDOM_LOG\f1 +.I indom +is not a defined instance domain identifier for the archive log +.IP \f3PM_ERR_INST_LOG\f1 +the external instance +.I name +is not known for the instance domain +.I indom +in the archive log diff --git a/man/man3/pmlookupindomtext.3 b/man/man3/pmlookupindomtext.3 new file mode 100644 index 0000000..d674e19 --- /dev/null +++ b/man/man3/pmlookupindomtext.3 @@ -0,0 +1,83 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMLOOKUPINDOMTEXT 3 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmLookupInDomText\f1 \- return text describing a performance metrics instance domain +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.sp +.nf +int pmLookupInDomText(pmInDom \fIindom\fP, int \fIlevel\fP, char **\fIbuffer\fP); +.fi +.sp +cc ... \-lpcp +.ft 1 +.SH DESCRIPTION +.de CW +.ie t \f(CW\\$1\f1\\$2 +.el \fI\\$1\f1\\$2 +.. +Provided the source of metrics from +the current +Performance Metrics Application Programming Interface (PMAPI) +context is a host, +retrieve descriptive text about the performance +metrics instance domain identified by +.IR indom . +.PP +The value for the instance domain +.I indom +is typically extracted from a +.CW pmDesc +structure, following a call to +.BR pmLookupDesc (3) +for a particular performance metric. +.PP +The argument +.I level +should be +.BR PM_TEXT_ONELINE +for a one-line summary, else +.BR PM_TEXT_HELP +for a more verbose description, suited to a help dialog. +.PP +The space pointed to by +.I buffer +will have been allocated in +.B pmLookupInDomText +with +.BR malloc (3C), +and it is the responsibility of the caller to +.BR free (3C) +the space when it is no longer required. +.PP +.B pmLookupInDomText +returns zero on success. +.SH SEE ALSO +.BR chkhelp (1), +.BR newhelp (1), +.BR PMAPI (3), +.BR pmGetConfig (3), +.BR pmLookupDesc (3), +.BR pmLookupText (3), +.BR pcp.conf (5) +and +.BR pcp.env (5). +.SH DIAGNOSTICS +.IP \f3PM_ERR_NOTHOST\f1 +if the current PMAPI context is an archive log +(help and one-line text is not maintained in the archive logs) diff --git a/man/man3/pmlookupipc.3 b/man/man3/pmlookupipc.3 new file mode 100644 index 0000000..b967470 --- /dev/null +++ b/man/man3/pmlookupipc.3 @@ -0,0 +1,98 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMLOOKUPIPC 3 "PCP" "Performance Co-Pilot" +.SH NAME +\f3__pmAddIPC\f1, +\f3__pmLookupIPC\f1, +\f3__pmFdLookupIPC\f1, +\f3__pmOverrideLastFd\f1, +\f3__pmPrintIPC\f1, +\f3__pmResetIPC\f1 \- IPC version infrastructure support +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.br +#include <pcp/impl.h> +.sp +int __pmAddIPC(int \fIfd\fP, __pmIPC \fIipc\fP); +.br +int __pmLookupIPC(__pmIPC **\fIipcp\fP); +.br +int __pmFdLookupIPC(int \fIfd\fP, __pmIPC **\fIipcp\fP); +.br +void __pmOverrideLastFd(int \fIfd\fP); +.br +void __pmPrintIPC(void); +.br +void __pmResetIPC(int \fIfd\fP); +.sp +cc ... \-lpcp +.ft 1 +.SH DESCRIPTION +IPC channels throughout the distributed PCP framework are affected by the +PCP 2.0 (and later) PDU changes. These functions are the interface to the libpcp IPC +connection management global data. This data consists of a hash table of +__pmIPC structures (indexed by file descriptor) and a cached, most-recently-used +file descriptor. +.PP +Newly created IPC channels must be registered with the hash table using +\f3__pmAddIPC\f1, such that the PDU sending and decoding routines can +determine whether they need to perform any PDU version translations or not, +for backward compatibility with previous the PCP 1.x IPC protocol. +.PP +.B __pmLookupIPC +and +.B __pmFdLookupIPC +both provide handles to the __pmIPC structure associated with the given file +descriptor, as previously established by a call to +.BR __pmAddIPC . +The difference between the two is that one allows an explicit file descriptor +lookup, and the other uses the cached, most-recently-used file descriptor. +So +.B __pmLookupIPC +actually calls +.B __pmFdLookupIPC +using this cached file descriptor as the argument. The justification for having +both is that in some places it is not possible to use +.B __pmFdLookupIPC +(which is preferred), since at that particular level of the PMAPI a file +descriptor is not available (see the __pmDecodeError code for an example). +.PP +The +.B __pmOverrideLastFd +is an escape mechanism for use in those situations where the last PDU +fetch did not go through the usual channels (ie. __pmGetPDU), so as to ensure +that the cached file descriptor is the correct file descriptor for the PDU +which is currently being processed. This will typically be used for archive +PDU processing or where version information is not available for a given file +descriptor (eg. immediately prior to a PDU version exchange). +.PP +.B __pmPrintIPC +is a useful debugging routine for displaying a table mapping all currently +registered file descriptors to their associated PDU version numbers. Unused +entries in this table should display the value zero in the version column. +.PP +.B __pmResetIPC +resets the version information associated with the given file descriptor to some +known (invalid) number. Subsequent lookups on this file descriptor will return +an UNKNOWN_VERSION embedded within the __pmIPC structure. +.SH SEE ALSO +.BR PMAPI (3) +.SH DIAGNOSTICS +A negative return value from \f3__pmLookupIPC\f1 indicates that the requested +file descriptor is not registered in the hash table. +This typically indicates closure of an IPC channel, so PM_ERR_IPC is returned +if this is the case. diff --git a/man/man3/pmlookupname.3 b/man/man3/pmlookupname.3 new file mode 100644 index 0000000..342c21e --- /dev/null +++ b/man/man3/pmlookupname.3 @@ -0,0 +1,93 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMLOOKUPNAME 3 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmLookupName\f1 \- translate performance metric names into PMIDs +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.sp +.nf +int pmLookupName(int \fInumpmid\fP, char **\fInamelist\fP, pmID *\fIpmidlist\fP); +.fi +.sp +cc ... \-lpcp +.ft 1 +.SH DESCRIPTION +.PP +Given a list in +.I namelist +containing +.I numpmid +full pathnames for performance metrics from a Performance Metrics Name +Space (PMNS), +.B pmLookupName +returns the list of associated +Performance Metric Identifiers (PMIDs) via +.IR pmidlist . +.PP +The result from +.B pmLookupName +will be the number of names translated in the absence of errors, else +an error code less than zero. +When errors are encountered, the corresponding value in +.I pmidlist +will be PM_ID_NULL. +.PP +Note that the error protocol guarantees there is a 1:1 relationship +between the elements of +.I namelist +and +.IR pmidlist , +hence both lists contain exactly +.I numpmid +elements. +For this reason, the caller is expected to have pre-allocated a suitably +sized array for +.IR pmidlist . +.SH SEE ALSO +.BR PMAPI (3), +.BR pmGetChildren (3), +.BR pmGetChildrenStatus (3), +.BR pmGetConfig (3), +.BR pmLoadNameSpace (3), +.BR pmNameID (3), +.BR pmNewContext (3), +.BR pcp.conf (5) +and +.BR pcp.env (5). +.SH DIAGNOSTICS +.IP \f3PM_ERR_TOOSMALL\f1 +.I numpmid +must be at least 1 +.IP \f3PM_ERR_NOPMNS\f1 +Failed to access a PMNS for operation. +Note that if the application hasn't a priori called +.BR pmLoadNameSpace (3) +and wants to use the distributed PMNS, then a call to +.B pmLookupName +must be made after the creation of a context (see +.BR pmNewContext (3)). +.IP \f3PM_ERR_NAME\f1 +One or more of the elements of +.I namelist +does not correspond to a valid metric name in the PMNS. +.IP \f3PM_ERR_NONLEAF\f1 +A name referred to a node in the PMNS but it was +not a leaf node. +.IP \f3PM_ERR_*\f1 +Other diagnostics are for protocol failures when +accessing the distributed PMNS. diff --git a/man/man3/pmlookuptext.3 b/man/man3/pmlookuptext.3 new file mode 100644 index 0000000..2115cfc --- /dev/null +++ b/man/man3/pmlookuptext.3 @@ -0,0 +1,71 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMLOOKUPTEXT 3 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmLookupText\f1 \- return text describing a performance metric +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.sp +.nf +int pmLookupText(pmID \fIpmid\fP, int \fIlevel\fP, char **\fIbuffer\fP); +.fi +.sp +cc ... \-lpcp +.ft 1 +.SH DESCRIPTION +Provided the source of metrics from +the current +Performance Metrics Application Programming Interface (PMAPI) +context is a host, +retrieve descriptive text about the performance +metric identified by +.IR pmid . +.PP +The argument +.I level +should be +.BR PM_TEXT_ONELINE +for a one-line summary, else +.BR PM_TEXT_HELP +for a more verbose description, suited to a help dialog. +.PP +The space pointed to by +.I buffer +will have been allocated in +.B pmLookupText +with +.BR malloc (3C), +and it is the responsibility of the caller to +.BR free (3C) +the space when it is no longer required. +.PP +.B pmLookupText +returns zero on success. +.SH SEE ALSO +.BR chkhelp (1), +.BR newhelp (1), +.BR PMAPI (3), +.BR pmGetConfig (3), +.BR pmLookupDesc (3), +.BR pmLookupInDomText (3), +.BR pcp.conf (5) +and +.BR pcp.env (5). +.SH DIAGNOSTICS +.IP \f3PM_ERR_NOTHOST\f1 +if the current PMAPI context is an archive log +(help and one-line text is not maintained in the archive logs) diff --git a/man/man3/pmmktime.3 b/man/man3/pmmktime.3 new file mode 100644 index 0000000..e9e6855 --- /dev/null +++ b/man/man3/pmmktime.3 @@ -0,0 +1,74 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMMKTIME 3 "PCP" "Performance Co-Pilot" +.SH NAME +\f3__pmMktime\f1 \- convert a \fBtm\fR structure to a calendar time +.SH "C SYNOPSIS" +.ft 3 +#include <time.h> +.br +#include <pcp/pmapi.h> +.br +#include <pcp/impl.h> +.sp +time_t *__pmMktime(struct tm *\fItimeptr\fP); +.sp +cc ... \-lpcp +.ft 1 +.SH DESCRIPTION +.B __pmMktime +is very similar to +.BR mktime (3), +except the timezone used is the current ``reporting timezone'' (rather than the +default +.B TZ +environment variable scheme). +.PP +Like +.BR mktime (3) +the time to be converted is passed via +.IR timeptr , +and +the function result +contains the calendar time (the number of seconds since 00:00:00 UTC, +January 1, 1970). +.PP +The default current reporting timezone is as defined by the +.B TZ +environment variable, so +.B __pmMktime +and +.BR mktime (3) +will initially produce similar conversions. +.PP +Use +.BR pmNewZone (3), +.BR pmNewContextZone (3) +or +.BR pmUseZone (3) +to establish a new current reporting timezone that will effect +.B __pmMktime +but not +.BR mktime (3). +.SH SEE ALSO +.BR mktime (3), +.BR PMAPI (3), +.BR pmCtime (3), +.BR pmLocaltime (3), +.BR pmNewContextZone (3), +.BR pmNewZone (3) +and +.BR pmUseZone (3). diff --git a/man/man3/pmnameall.3 b/man/man3/pmnameall.3 new file mode 100644 index 0000000..aaeb0a3 --- /dev/null +++ b/man/man3/pmnameall.3 @@ -0,0 +1,98 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMNAMEALL 3 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmNameAll\f1 \- translate a PMID to a set of performance metric names +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.sp +.nf +int pmNameAll(pmID \fIpmid\fP, char ***\fInameset\fP); +.fi +.sp +cc ... \-lpcp +.ft 1 +.SH DESCRIPTION +.de CW +.ie t \f(CW\\$1\f1\\$2 +.el \fI\\$1\f1\\$2 +.. +Given a +Performance Metric ID (PMID) via +.IR pmid , +.B pmNameAll +will +determine all the corresponding metric names, if any, in the +Performance Metrics Name Space (PMNS), and return these via +.IR nameset . +.PP +The resulting list of pointers +.I nameset +.B and +the values +(the relative names) that the pointers reference will have been +allocated by +.B pmNameAll +with a single call to +.BR malloc (3C), +and it is the +responsibility of the +.B pmNameAll +caller to +.CW free(nameset) +to release the space +when it is no longer required. +.PP +In the absence of errors, +.B pmNameAll +returns the number of names in +.IR nameset . +.PP +For many examples of a PMNS, there will be a 1:1 mapping between +a name and a PMID, and under these circumstances, +.BR pmNameID (3) +provides a slightly simpler interface in the absence of duplicate +names for a particular PMID. +.SH SEE ALSO +.BR PMAPI (3), +.BR pmGetChildren (3), +.BR pmGetChildrenStatus (3), +.BR pmGetConfig (3), +.BR pmLoadASCIINameSpace (3), +.BR pmLoadNameSpace (3), +.BR pmLookupName (3), +.BR pmNameID (3), +.BR pmNewContext (3), +.BR pcp.conf (5), +.BR pcp.env (5) +and +.BR pmns (5). +.SH DIAGNOSTICS +.IP \f3PM_ERR_NOPMNS\f1 +Failed to access a PMNS for operation. +Note that if the application hasn't a priori called +.BR pmLoadNameSpace (3) +and wants to use the distributed PMNS, then a call to +.B pmNameAll +must be made after the creation of a context (see +.BR pmNewContext (3)). +.IP \f3PM_ERR_PMID\f1 +.I pmid +does not correspond to a defined PMID in the PMNS. +.IP \f3PM_ERR_*\f1 +Other diagnostics are for protocol failures when +accessing the distributed PMNS. diff --git a/man/man3/pmnameid.3 b/man/man3/pmnameid.3 new file mode 100644 index 0000000..e74cac3 --- /dev/null +++ b/man/man3/pmnameid.3 @@ -0,0 +1,87 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMNAMEID 3 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmNameID\f1 \- translate a PMID to a performance metric name +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.sp +.nf +int pmNameID(pmID \fIpmid\fP, char **\fIname\fP); +.fi +.sp +cc ... \-lpcp +.ft 1 +.SH DESCRIPTION +Given a +Performance Metric ID (PMID) via +.IR pmid , +.B pmNameID +will +determine the corresponding metric name, if any, in the +Performance Metrics Name Space (PMNS), and return this via +.IR name . +.PP +If the PMNS contains multiple names associated with the requested +PMID, one of these will be returned via +.IR name , +but there is no way to determine which of the duplicate names +this will be. See +.BR pmNameAll (3) +if all of the corresponding names are required. +.PP +.I name +is a null-byte terminated string, allocated by +.B pmNameID +using +.BR malloc (3C) +and it is the caller's responsibility to call +.BR free (3C) +to release the storage when the value is no longer required. +.PP +In the absence of errors, +.B pmNameID +returns zero. +.SH SEE ALSO +.BR PMAPI (3), +.BR pmGetChildren (3), +.BR pmGetChildrenStatus (3), +.BR pmGetConfig (3), +.BR pmLoadASCIINameSpace (3), +.BR pmLoadNameSpace (3), +.BR pmLookupName (3), +.BR pmNameAll (3), +.BR pmNewContext (3), +.BR pcp.conf (5), +.BR pcp.env (5) +and +.BR pmns (5). +.SH DIAGNOSTICS +.IP \f3PM_ERR_NOPMNS\f1 +Failed to access a PMNS for operation. +Note that if the application hasn't a priori called +.BR pmLoadNameSpace (3) +and wants to use the distributed PMNS, then a call to +.B pmNameId +must be made after the creation of a context (see +.BR pmNewContext (3)). +.IP \f3PM_ERR_PMID\f1 +.I pmid +does not correspond to a defined PMID in the PMNS. +.IP \f3PM_ERR_*\f1 +Other diagnostics are for protocol failures when +accessing the distributed PMNS. diff --git a/man/man3/pmnameindom.3 b/man/man3/pmnameindom.3 new file mode 100644 index 0000000..2e22134 --- /dev/null +++ b/man/man3/pmnameindom.3 @@ -0,0 +1,83 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMNAMEINDOM 3 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmNameInDom\f1 \- translate an instance identifier into an instance name +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.sp +.nf +int pmNameInDom(pmInDom \fIindom\fP, int \fIinst\fP, char **\fIname\fP); +.fi +.sp +cc ... \-lpcp +.ft 1 +.SH DESCRIPTION +.de CW +.ie t \f(CW\\$1\f1\\$2 +.el \fI\\$1\f1\\$2 +.. +For the instance domain +.IR indom , +in the current +Performance Metrics Application Programming Interface (PMAPI) +context, +locate the instance with the internal instance identifier given +by +.IR inst , +and return the full external instance identification via +.IR name . +.PP +The value for the instance domain +.I indom +is typically extracted from a +.CW pmDesc +structure, following a call to +.BR pmLookupDesc (3) +for a particular performance metric. +.PP +The space for the value of +.I name +will have been allocated in +.B pmNameInDom +with +.BR malloc (3C), +and it is the responsibility of the caller to +.BR free (3C) +the space when it is no longer required. +.PP +.B pmNameInDom +returns zero on success. +.SH SEE ALSO +.BR PMAPI (3), +.BR pmGetConfig (3), +.BR pmGetInDom (3), +.BR pmLookupInDom (3), +.BR pmNameInDomArchive (3), +.BR pcp.conf (5) +and +.BR pcp.env (5). +.SH DIAGNOSTICS +.IP \f3PM_ERR_INDOM\f1 +.I indom +is not a valid instance domain identifier +.IP \f3PM_ERR_INST\f1 +The instance identifier +.I inst +is not known for the instance domain +.I indom +in the current PMAPI context diff --git a/man/man3/pmnameindomarchive.3 b/man/man3/pmnameindomarchive.3 new file mode 100644 index 0000000..a9ff37e --- /dev/null +++ b/man/man3/pmnameindomarchive.3 @@ -0,0 +1,89 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMNAMEINDOMARCHIVE 3 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmNameInDomArchive\f1 \- translate an instance identifier into an instance name +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.sp +int pmNameInDomArchive(pmInDom \fIindom\fP, int \fIinst\fP, char **\fIname\fP); +.sp +cc ... \-lpcp +.ft 1 +.SH DESCRIPTION +.de CW +.ie t \f(CW\\$1\f1\\$2 +.el \fI\\$1\f1\\$2 +.. +Provided that the current +Performance Metrics Application Programming Interface (PMAPI) +context is associated with an archive log, +.B pmNameInDomArchive +will scan the union of all the instance domain metadata +for the instance domain +.IR indom , +locate the first instance with the internal instance identifier given +by +.IR inst , +and return the full external instance identification via +.IR name . +.PP +This routine is a specialized version of the more general PMAPI +routine +.BR pmNameInDom . +.PP +The value for the instance domain +.I indom +is typically extracted from a +.CW pmDesc +structure, following a call to +.BR pmLookupDesc (3) +for a particular performance metric. +.PP +The space for the value of +.I name +will have been allocated in +.B pmNameInDomArchive +with +.BR malloc (3C), +and it is the responsibility of the caller to +.BR free (3C) +the space when it is no longer required. +.PP +.B pmNameInDomArchive +returns zero on success. +.SH SEE ALSO +.BR PMAPI (3), +.BR pmGetConfig (3), +.BR pmGetInDomArchive (3), +.BR pmLookupInDomArchive (3), +.BR pmNameInDom (3), +.BR pcp.conf (5) +and +.BR pcp.env (5). +.SH DIAGNOSTICS +.IP \f3PM_ERR_NOTARCHIVE\f1 +the current PMAPI context is not associated with an archive log +.IP \f3PM_ERR_INDOM_LOG\f1 +.I indom +is not a defined instance domain identifier for the archive log +.IP \f3PM_ERR_INST_LOG\f1 +the instance identifier +.I inst +is not known for the instance domain +.I indom +in the archive log diff --git a/man/man3/pmnewcontext.3 b/man/man3/pmnewcontext.3 new file mode 100644 index 0000000..2286c69 --- /dev/null +++ b/man/man3/pmnewcontext.3 @@ -0,0 +1,282 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMNEWCONTEXT 3 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmNewContext\f1 \- establish a new PMAPI context +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.sp +int pmNewContext(int \fItype\fP, const char *\fIname\fP); +.sp +cc ... \-lpcp +.ft 1 +.SH DESCRIPTION +An application using the +Performance Metrics Application Programming Interface (PMAPI) +may manipulate several concurrent contexts, +each associated with a source of performance metrics, e.g. \c +.BR pmcd (1) +on some host, or an archive log of performance metrics as created by +.BR pmlogger (1), +or a standalone connection on the local host that does not involve +.BR pmcd (1). +.PP +.BR pmNewContext +may be used to establish a new context. +The source of the metrics is identified by +.IR name , +and may be either a host name (\c +.I type +is +.BR PM_CONTEXT_HOST ), +or the base name common to all of the physical files of an archive log (\c +.I type +is +.BR PM_CONTEXT_ARCHIVE ). +.PP +For a +.I type +of +.BR PM_CONTEXT_HOST , +in addition to identifying a host +the +.I name +may also be used to encode additional optional information in the form of +a +.BR pmcd (1) +port number, a +.BR pmproxy (1) +hostname and a proxy port number. For example the +.I name +\&"app23:14321,4321@firewall.example.com:11111" +specifies +a connection on port +.I 14321 +(or port +.I 4321 +if +.I 14321 +is unavailable) +to +.BR pmcd (1) +on the host +.I app23 +via port +.I 11111 +to +.BR pmproxy (1) +on the host +.IR firewall.example.com . +.PP +For a +.I type +of +.BR PM_CONTEXT_ARCHIVE , +.I name +may also be the name of any of the physical files of an +archive, e.g. +.IB myarchive .meta +(the metadata file) or +.IB myarchive .index +(the temporal index) or +.IB myarchive .0 +(the first data volume of the archive) +or +.IB myarchive .0.bz2 +or +.IB myarchive .0.bz +(the first data volume compressed with +.BR bzip2 (1)) +or +.IB myarchive .0.gz +or +.IB myarchive .0.Z +or +.IB myarchive .0.z +(the first data volume compressed with +.BR gzip (1)), +.IB myarchive .1 +or +.IB myarchive .3.bz2 +or +.IB myarchive .42.gz +etc. +.PP +In the case where +.I type +is +.BR PM_CONTEXT_LOCAL , +.I name +is ignored, and the context uses a standalone connection to the +PMDA methods used by +.BR pmcd (1). +When this type of context is used, the range of accessible performance +metrics is constrained to those from the operating system, and optionally +the ``proc'', ``sample'' and ``ib'' PMDAs. +.PP +In the case where \f2type\fP is \f3PM_CONTEXT_HOST\fP, additional flags can +be added to the \f2type\fP to indicate if the connection to \f3pmcd\fP(1) +should be encrypted (\f3PM_CTXFLAG_SECURE\fP), deferred (\f3PM_CTXFLAG_SHALLOW\fP) +and if the file descriptor used to communicate with \f3pmcd\fP(1), should not be +shared across contexts (\f3PM_CTXFLAG_EXCLUSIVE\fP). These final two context +flags are now deprecated and ignored. +.PP +The initial instance +profile is set up to select all instances in all instance domains. +In the case of an archive, +the initial collection time is also set to zero, +so that an initial +.BR pmFetch (3) +will result in the earliest set of metrics +being returned from the archive. +.PP +Once established, the association between a context and a source of metrics +is fixed for the life of the context, however routines are provided to +independently manipulate both the instance profile (see +.BR pmAddProfile (3) +and +.BR pmDelProfile (3)) +and the collection time for archives (see +.BR pmSetMode (3)). +.PP +.B pmNewContext +returns a handle that may be used with subsequent calls to +.BR pmUseContext (3). +.PP +The new context remains the current PMAPI context for all +subsequent calls across the PMAPI, +until another call to +.BR pmNewContext (3) +is made, or the context is explicitly changed with a call to +.BR pmDupContext (3) +or +.BR pmUseContext (3), +or destroyed using +.BR pmDestroyContext (3). +.PP +When attempting to connect to a remote +.BR pmcd (1) +on a machine that is booting, +.B pmNewContext +could potentially block for a long time until the remote machine +finishes its initialization. +.B pmNewContext +will 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 +.B PMCD_CONNECT_TIMEOUT +in the environment to a real number of seconds for the +desired timeout. +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. +.SH ENVIRONMENT +.TP +.B PMCD_CONNECT_TIMEOUT +Timeout period (in seconds) for +.BR pmcd (1) +connection attempts. +.TP +.B PMCD_PORT +TCP/IP port(s) for connecting to +.BR pmcd (1), +historically was 4321 and more recently the officially registered port +44321; in the current release, +.B pmcd +listens on both these ports as a transitional arrangement. If used, +should be set to a comma-separated list of numerical port numbers. +.TP +.B PMDA_PATH +When searching for PMDAs to be loaded when +.I type +is +.BR PM_CONTEXT_LOCAL , +the +.B PMDA_PATH +environment variable may be used to define a search path of +directories to be used to locate the PMDA executables. +The default search path is +.BR $PCP_SHARE_DIR/lib:/usr/pcp/lib . +.SH CAVEATS +When using a +.I type +of +.BR PM_CONTEXT_LOCAL , +the operating system PMDA may export data structures directly +from the kernel, which means that the +.B pmNewContext +caller should be an +executable program compiled for the same object code format +as the booted kernel. +.P +In addition, applications using a +.B PM_CONTEXT_LOCAL +context +must be single-threaded because the various DSO PMDAs may not be +thread-safe. This restriction is enforced at the +.BR PMAPI (3), +where routines may return the error code +.B PM_ERR_THREAD +if the library detects calls from more than one thread. +.P +Applications that use +.BR gethostbyname (3N) +should exercise caution because the static fields in +.I "struct hostent" +may not be preserved across some +.BR PMAPI (3) +calls. +In particular, +.BR pmNewContext (3) +and +.BR pmReconnectContext (3) +both may call +.BR gethostbyname (3N) +internally. +.SH SEE ALSO +.BR pmcd (1), +.BR pmproxy (1), +.BR pmAddProfile (3), +.BR PMAPI (3), +.BR pmDelProfile (3), +.BR pmDestroyContext (3), +.BR pmDupContext (3), +.BR pmGetConfig (3), +.BR pmReconnectContext (3), +.BR pmSetMode (3), +.BR pmUseContext (3), +.BR pmWhichContext (3), +.BR pcp.conf (5) +and +.BR pcp.env (5). +.SH DIAGNOSTICS +.P +.B PM_ERR_PERMISSION +.IP +No permission to perform requested operation +.P +.B PM_ERR_CONNLIMIT +.IP +PMCD connection limit for this host exceeded +.P +.B PM_ERR_NOCONTEXT +.IP +Requested context type was not +.BR PM_CONTEXT_LOCAL , +.B PM_CONTEXT_HOST +or +.BR PM_CONTEXT_ARCHIVE . diff --git a/man/man3/pmnewcontextzone.3 b/man/man3/pmnewcontextzone.3 new file mode 100644 index 0000000..f7e05f9 --- /dev/null +++ b/man/man3/pmnewcontextzone.3 @@ -0,0 +1,80 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMNEWCONTEXTZONE 3 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmNewContextZone\f1 \- establish a reporting timezone based on a PMAPI context +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.sp +int pmNewContextZone(void); +.sp +cc ... \-lpcp +.ft 1 +.SH DESCRIPTION +.de CW +.ie t \f(CW\\$1\f1\\$2 +.el \fI\\$1\f1\\$2 +.. +The current reporting timezone affects the timezone used by +.BR pmCtime (3) +and +.BR pmLocaltime (3). +.PP +If the current PMAPI context is an archive, +.B pmNewContextZone +uses the timezone from the archive label record to +set the current reporting timezone. +.PP +If the current PMAPI context +corresponds to a host source of metrics, +.B pmNewContextZone +executes a +.BR pmFetch (3) +to retrieve the value for the metric +.CW pmcd.timezone +and uses that to set the current reporting timezone. +.PP +In both cases, +.B pmNewContextZone +returns a value to identify the current reporting timezone +that may be +used in a subsequent call to +.BR pmUseZone (3) +to restore this reporting timezone. +.SH SEE ALSO +.BR PMAPI (3), +.BR pmCtime (3), +.BR pmFetch (3), +.BR pmGetConfig (3), +.BR pmLocaltime (3), +.BR pmNewContext (3), +.BR pmNewZone (3), +.BR pmUseZone (3), +.BR pmWhichZone (3), +.BR pcp.conf (5), +.BR pcp.env (5) +and +.BR environ (5). +.SH DIAGNOSTICS +.TP +.B PM_ERR_NOCONTEXT +the current PMAPI context is not valid +.TP +other +a return value less than zero indicates a fatal error from a system call, +most likely +.BR malloc (3C) diff --git a/man/man3/pmnewzone.3 b/man/man3/pmnewzone.3 new file mode 100644 index 0000000..3f460c0 --- /dev/null +++ b/man/man3/pmnewzone.3 @@ -0,0 +1,60 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMNEWZONE 3 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmNewZone\f1 \- establish a reporting timezone +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.sp +int pmNewZone(const char *\fItz\fP); +.sp +cc ... \-lpcp +.ft 1 +.SH DESCRIPTION +The current reporting timezone affects the timezone used by +.BR pmCtime (3) +and +.BR pmLocaltime (3). +.PP +The argument +.I tz +defines a timezone string, in the format described for the +.B TZ +environment variable, see +.BR environ (5). +.PP +.B pmNewZone +sets the current reporting timezone, and returns a value that may be +used in a subsequent call to +.BR pmUseZone (3) +to restore this reporting timezone. +.SH SEE ALSO +.BR PMAPI (3), +.BR pmCtime (3), +.BR pmGetConfig (3), +.BR pmLocaltime (3), +.BR pmNewContextZone (3), +.BR pmUseZone (3), +.BR pmWhichZone (3), +.BR pcp.conf (5), +.BR pcp.env (5) +and +.BR environ (5). +.SH DIAGNOSTICS +A return value less than zero indicates a fatal error from a system call, +most likely +.BR malloc (3C). diff --git a/man/man3/pmnumberstr.3 b/man/man3/pmnumberstr.3 new file mode 100644 index 0000000..d347461 --- /dev/null +++ b/man/man3/pmnumberstr.3 @@ -0,0 +1,84 @@ +'\"! tbl | mmdoc +'\"macro stdmacro +.\" +.\" Copyright (c) 2000-2004 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMNUMBERSTR 3 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmNumberStr\f1, +\f3pmNumberStr_r\f1 \- fixed width output format for numbers +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.sp +const char *pmNumberStr(double \fIvalue\fP); +.br +char *pmNumberStr_r(double \fIvalue\fP, char *\fIbuf\fP, int \fIbuflen\fP); +.sp +cc ... \-lpcp +.ft 1 +.SH DESCRIPTION +.B pmNumberStr +returns the address of a 8-byte buffer that holds a +null-byte terminated representation of +.I value +suitable for output with fixed width fields. +The +.B pmNumberStr_r +function does the same, but stores the result in a user-supplied buffer +.I buf +of length +.IR buflen , +which should have room for at least 8 bytes. +.PP +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. +.PP +The format depends on the sign and magnitude of +.I value +as follows (\c +\f(COd\f1 +represents a decimal digit): +.TS +box,center; +c | c +lf(CW) | lf(CO). +\f2value\f1 range format +_ + > 999995000000000 \f(CBinf?\fP +999995000000000 \- 999995000000 ddd.dd\f(CBT\fP + 999995000000 \- 999995000 ddd.dd\f(CBG\fP + 999995000 \- 999995 ddd.dd\f(CBM\fP + 999995 \- 999.995 ddd.dd\f(CBK\fP + 999.995 \- 0.005 ddd.dd + 0.005 \- \-0.005 \f(CB 0.00\fP + \-0.005 \- \-99.95 \-dd.dd + \-99.995 \- \-99995 \-dd.dd\f(CBK\fP + \-99995 \- \-99995000 \-dd.dd\f(CBM\fP + \-99995000 \- \-99995000000 \-dd.dd\f(CBG\fP + \-99995000000 \- \-99995000000000 \-dd.dd\f(CBT\fP + < \-99995000000000 \f(CB\-inf?\fP +.TE +.PP +At the boundary points of the ranges, the chosen format will retain the +maximum number of significant digits. +.SH NOTES +.B pmNumberStr +returns a pointer to a static buffer and hence is not thread-safe. +Multi-threaded applications should use +.B pmNumberStr_r +instead. +.SH SEE ALSO +.BR printf (3) diff --git a/man/man3/pmopenlog.3 b/man/man3/pmopenlog.3 new file mode 100644 index 0000000..dd0baff --- /dev/null +++ b/man/man3/pmopenlog.3 @@ -0,0 +1,80 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000-2004 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMOPENLOG 3 "PCP" "Performance Co-Pilot" +.SH NAME +\f3__pmOpenLog\f1 \- create a log file for diagnostics and debug output +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.br +#include <pcp/impl.h> +.sp +.ad l +.hy 0 +.in +8n +.ti -8n +FILE *__pmOpenLog(const char *\fIprogname\fP, const char *\fIlogname\fP, FILE\ *\fIoldstream\fP, int\ *\fIstatus\fP); +.sp +.in +.hy +.ad +cc ... \-lpcp +.ft 1 +.SH DESCRIPTION +.B __pmOpenLog +reassigns the standard I/O stream +.I oldstream +to be associated with the file +.IR logname . +If it already exists, +.I logname +will be removed and recreated if possible (to ensure correct ownership +and permissions from the caller to +.BR __pmOpenLog ). +.PP +On return, the function value is the new standard I/O stream. In the +event of an error, this will be +.I oldstream +unchanged and +.I status +will be 0. +.PP +For success, +.I status +is 1, a standard preamble is written to +.I logname +.ti +0.5i +.ft B +Log for \fIprogname\fB on \fIhostname\fB started \fIdate and time\fB +.ft R +.br +and an +.BR atexit (3) +handler is installed to write the postscript message to +.I logname +.ti +0.5i +.ft B +Log finished \fIdate and time\fB +.ft R +.br +when the processes exits. +.PP +.I progname +is only used to annotate messages. +.SH SEE ALSO +.BR atexit (3) +and +.BR freopen (3). diff --git a/man/man3/pmparsectime.3 b/man/man3/pmparsectime.3 new file mode 100644 index 0000000..6ec29d5 --- /dev/null +++ b/man/man3/pmparsectime.3 @@ -0,0 +1,71 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000-2004 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMPARSECTIME 3 "PCP" "Performance Co-Pilot" +.SH NAME +\f3__pmParseCtime\f1 \- convert \fBctime\fR(3) string to \fBtm\fR structure +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.br +#include <pcp/impl.h> +.sp +int __pmParseCtime(const char *\fIstring\fP, struct tm *\fIrslt\fP, char **\fIerrmsg\fP); +.sp +cc ... \-lpcp +.ft 1 +.SH DESCRIPTION +.B __pmParseCtime +reverses the +.BR asctime (3C) +function. It accepts a +.B string +specifying a time, and fills in the given +.B tm +structure. +.PP +Either a fully specified +.BR asctime (3C) +string like "Mon Mar 4 13:07:47 1996" or a partially specified time +like '1996", "Mar 1996", "Mar 4 1996", "Mar", "13:07:47", "13:07", +"Mar 4 13:07:47",... is accepted. In addition, the seconds component +may be a floating point number, for example "13:07:47.5". The 12 hour +clock is also supported, so "13:07" and "1:07 pm" are equivalent. +.PP +.B __pmParseCtime +returns 0 if successful. It returns \-1 and a dynamically allocated +error message string in +.BR errmsg , +if the given +.B string +does not parse. Be sure to +.BR free (3C) +the error message string. +.PP +The +.B tm +structure returned in +.B rslt +should only be used as an argument to the +.B __pmConvertTime +function, as it contains encoded information that will only be +correctly interpreted by +.BR __pmConvertTime . +.SH SEE ALSO +.BR PMAPI (3), +.BR pmParseInterval (3), +.BR __pmConvertTime (3) +and +.BR __pmParseTime (3). diff --git a/man/man3/pmparsedebug.3 b/man/man3/pmparsedebug.3 new file mode 100644 index 0000000..54faac5 --- /dev/null +++ b/man/man3/pmparsedebug.3 @@ -0,0 +1,68 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000-2004 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMPARSEDEBUG 3 "PCP" "Performance Co-Pilot" +.SH NAME +\f3__pmParseDebug\f1 \- convert a list of debug flags into an integer +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.br +#include <pcp/impl.h> +.sp +int __pmParseDebug(const char *\fIspec\fP); +.sp +cc ... \-lpcp +.ft 1 +.SH DESCRIPTION +.B __pmParseDebug +parses +.I spec +assuming it to be a comma separated list of PCP debug flags. +.PP +Each flag may be specified as an integer or the +trailing portion of the symbolic name of the corresponding flag as reported +by +.BR pmdbg (1). +Symbolic names are stripped of the ``DBG_TRACE_'' prefix and may appear +in either case. +.PP +As a special case, the values ``\-1'' and ``ALL'' are treated as synonyms +for turning on all bits except the sign bit in the result, i.e. \c +.B INT_MAX +from +.IR <limits.h> . +.PP +For example the debug flag +.B DBG_TRACE_FETCH +is defined in +.I /usr/include/pcp/impl.h +and may be specified in +.I spec +as +.BR 2 , +.B FETCH +or +.BR fetch . +.SH SEE ALSO +.BR pmdbg (1) +.SH DIAGNOSTICS +If successful, +.B __pmParseDebug +returns the value computed by the bit-wise ``or'' of each flag in the +.IR spec , +suitable for assigning to the global debug trace control variable +.BR pmDebug . +Otherwise the return value is less than 0 to indicate a parsing error. diff --git a/man/man3/pmparsehostattrsspec.3 b/man/man3/pmparsehostattrsspec.3 new file mode 100644 index 0000000..60d87cb --- /dev/null +++ b/man/man3/pmparsehostattrsspec.3 @@ -0,0 +1,248 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2013 Red Hat. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.TH PMPARSEHOSTATTRSSPEC 3 "PCP" "Performance Co-Pilot" +.SH NAME +\f3__pmParseHostAttrsSpec\f1, +\f3__pmUnparseHostAttrsSpec\f1, +\f3__pmFreeHostAttrsSpec\f1, +\f3__pmFreeAttrsSpec\f1 \- host and attributes specification parser +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.br +#include <pcp/impl.h> +.sp +.ad l +.hy 0 +.in +8n +.ti -8n +int __pmParseHostAttrsSpec(const char *\fIstring\fP, pmHostSpec **\fIhostsp\fP, int\ *\fIcount\fP, __pmHashCtl\ *\fIattrs\fP, char\ **\fIerrmsg\fP); +.br +.ti -8n +int __pmUnparseHostAttrsSpec(pmHostSpec *\fIhostsp\fP, int\ *\fIcount\fP, __pmHashCtl\ *\fIattrs\fP, char\ *\fIstring\fP, size_t \fIsize\fP); +.br +.ti -8n +void __pmFreeHostAttrsSpec(pmHostSpec *\fIhosts\fP, int \fIcount\fP, __pmHashCtl\ *\fIattrs\fP); +.br +.ti -8n +void __pmFreeAttrsSpec(__pmHashCtl\ *\fIattrs\fP); +.sp +.in +.hy +.ad +cc ... \-lpcp +.ft 1 +.SH DESCRIPTION +.B __pmParseHostAttrsSpec +accepts a +.B string +specifying the location of a PCP performance metric collector daemon, +and any attributes that should be associated with the connection to that +daemon. +.PP +The syntax allows the optional specification of a protocol (native PCP +protocol, encrypted PCP protocol or unix domain socket protocol). +.PP +If the specified protocol is native PCP protocol, or encrypted PCP protocol, +an initial +.BR pmcd (1) +hostname with optional port numbers and optional proxy host, +and optional attributes which are to be associated with the connection may be specified. +Some examples follow: +.PP +.in +0.5i +.nf +.ft CW +pcp://nas1.servers.com:44321@firewalls.r.us?compress +pcps://nas1.servers.com?user=otto&pass=blotto&compress +.ft R +.fi +.in +.PP +If the specified protocol is a unix domain socket protocol, the path +to the socket in the local file system may be specified along with +optional attributes which are to be associated with the connection. +For example: +.PP +.in +0.5i +.nf +.ft CW +unix://$PCP_RUN_DIR/pmcd.socket:?compress +local://my/local/pmcd.socket:?user=otto&pass=blotto&compress +.ft R +.fi +.in +.PP +If the optional protocol component is not specified, then the default +setting will be used - which is the native PCP binary protocol. +However, this can still be overwritten via the environment as described +in +.BR PCPIntro (1). +If the protocol prefix is specified, it must be one of either "pcp://" +(clear), "pcps://" (secure, encrypted), "unix://" (authenticated local) +or "local://" ("unix://" then "pcp://"). +.PP +The path specified for the "unix://" and "local://" protocols will always be +interpreted as an absolute path name. For example, the following are all +interpreted identically as +.IR $PCP_RUN_DIR/pmcd.socket . +.PP +.in +0.5i +.nf +.ft CW +unix://$PCP_RUN_DIR/pmcd.socket +unix:/$PCP_RUN_DIR/pmcd.socket +unix:$PCP_RUN_DIR/pmcd.socket +.ft R +.fi +.in +.PP +Refer to +.BR __pmParseHostSpec (3) +for further details of the host and proxy host components. +.PP +If any optional connection attributes are to be specified, these are +separated from the hostname component via the '?' character. +Each attribute is separated by the '&' character, and each can be +either a simple attribute flag (such as "compress") or a name=value +pair (such as "username=fred"). +.PP +.B __pmParseHostAttrsSpec +takes a null-terminated host-and-attributes specification +.B string +and returns an array of +.B pmHostSpec +structures, where the array has +.B count +entries, and an +.B attrs +hash table containing any attributes (including the +optional protocol, if it was specified). +.PP +Full details of the +.B pmHostSpec +structures are provided in +.BR __pmParseHostSpec (3). +.PP +The +.B __pmHashCtl +structure that is filled out on return via +.BR attributes , +represents each individual attribute in the specification +.B string +with any associated value. +It should be considered an opaque structure and should be zeroed +beforehand. +.PP +The returned hash table control structure can be iterated using +one of the supplied iteration mechanisms \- +.B __pmHashWalkCB +(a callback-based mechanism) +or +.B __pmHashWalk +(a simple procedural mechanism). +These provide access to the individual hash nodes, as +.B __pmHashNode +entries, which provide access to decoded attributes and their +(optional) values. +.PP +.nf +.ft CW + typedef struct __pmHashNode { + __pmHashNode *next; /* next node in hash bucket (internal) */ + unsigned int key; /* key identifying particular attribute */ + void *data; /* attributes value (optional, string) */ + } __pmHashNode; +.fi +.PP +There are a set number of valid attributes, however these may be +extended in future releases as new connection parameters become +needed. +These can be identified via the PCP_ATTR_* macros in the PCP header +files. +.PP +.B __pmUnparseHostSpec +performs the inverse operation, creating a +.B string +representation from +.B hosts +and +.B attributes +structures. +The size of the supplied +.B string +buffer must be provided by the caller using the +.B size +parameter. +.SH "RETURN VALUE" +If the given +.B string +is successfully parsed +.B __pmParseHostAttrsSpec +returns zero. +In this case the dynamic storage allocated by +.B __pmParseHostAttrsSpec +can be released by calling +.B __pmFreeHostAttrsSpec +using the addresses returned from +.B __pmParseHostAttrsSpec +.P +Alternatively, the +.B hosts +and +.B attributes +memory can be freed separately, using +.BR __pmFreeHostSpec (3) +and +.BR __pmFreeAttrsSpec . +.P +.B __pmParseHostAttrsSpec +returns +.B PM_ERR_GENERIC +and a dynamically allocated error message string in +.BR errmsg , +if the given +.B string +does not parse, and the user-supplied +.B errmsg +pointer is non-null. +Be sure to +.BR free (3C) +the error message string in this situation. +.PP +In the case of an error, both +.B hosts +and +.B attributes +are undefined. +In the case of success, +.B errmsg +is undefined. +.PP +On success +.B __pmUnparseHostAttrsSpec +returns a positive value indicating the number of characters written +into the supplied buffer. +However, if the supplied buffer was too small, a negative status code of +.B \-E2BIG +will be returned. +.SH SEE ALSO +.BR pmcd (1), +.BR pmproxy (1), +.BR pmchart (1), +.BR __pmParseHostSpec (3), +.BR PMAPI (3) +and +.BR pmNewContext (3). diff --git a/man/man3/pmparsehostspec.3 b/man/man3/pmparsehostspec.3 new file mode 100644 index 0000000..f2351fd --- /dev/null +++ b/man/man3/pmparsehostspec.3 @@ -0,0 +1,168 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2013 Red Hat. +.\" Copyright (c) 2007 Aconex, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.TH PMPARSEHOSTSPEC 3 "PCP" "Performance Co-Pilot" +.SH NAME +\f3__pmParseHostSpec\f1, +\f3__pmUnparseHostSpec\f1, +\f3__pmFreeHostSpec\f1 \- uniform host specification parser +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.br +#include <pcp/impl.h> +.sp +.ad l +.hy 0 +.in +8n +.ti -8n +int __pmParseHostSpec(const char *\fIstring\fP, pmHostSpec **\fIhostsp\fP, int\ *\fIcount\fP, char\ **\fIerrmsg\fP); +.br +.ti -8n +int __pmUnparseHostSpec(pmHostSpec *\fIhosts\fP, int \fIcount\fP, char *\fIstring\fP, size_t \fIsize\fP); +.br +.ti -8n +void __pmFreeHostSpec(pmHostSpec *\fIhosts\fP, int \fIcount\fP); +.sp +.in +.hy +.ad +cc ... \-lpcp +.ft 1 +.SH DESCRIPTION +.B __pmParseHostSpec +accepts a +.B string +specifying the location of a PCP performance metric collector daemon. +The syntax of the various formats of this +.B string +is described in +.BR PCPIntro (1) +where several examples are also presented. +.PP +The syntax allows the initial +.BR pmcd (1) +hostname to be optionally followed by a list of port numbers, +which will be tried in order when connecting to +.B pmcd +on that host. +The portlist is separated from the hostname using a colon, and +each port in the list is comma-separated. +.PP +In addition, one or more optional +.BR pmproxy (1) +hosts can be specified (currently, only one proxy host is supported +by the PCP protocols). +These are separated from each other and from the +.B pmcd +component using the @ character. +These may also be followed by an optional port list, using the +same comma-separated syntax as before. +.PP +.B __pmParseHostSpec +takes a null-terminated host specification +.B string +and returns an array of +.B pmHostSpec +structures, where the array has +.B count +entries. +.PP +These +.B pmHostSpec +structures that are returned via +.B hostsp +represent each individual host in the specification +.B string +and has the following +declaration: +.PP +.nf +.ft CW + typedef struct { + char *name; /* hostname (always valid) */ + int *ports; /* array of host port numbers */ + int nports; /* number of ports in host port array */ + } pmHostSpec; +.fi +.PP +.B __pmUnparseHostSpec +performs the inverse operation, creating a +.B string +representation from a number of +.B hosts +structures. +Where the +.B count +of structures indicated by +.B hosts +is greater than one, the proxy syntax is used to indicate a chain of +proxied hosts. +The size of the supplied +.B string +buffer must be provided by the caller using the +.B size +parameter. +.SH "RETURN VALUE" +If the given +.B string +is successfully parsed +.B __pmParseHostSpec +returns zero. +In this case the dynamic storage allocated by +.B __pmParseHostSpec +can be released by calling +.B __pmFreeHostSpec +using the address returned from +.B __pmParseHostSpec +via +.BR hosts . +.P +.B __pmParseHostSpec +returns +.B PM_ERR_GENERIC +and a dynamically allocated error message string in +.BR errmsg , +if the given +.B string +does not parse, and the user-supplied +.B errmsg +pointer is non-null. +Be sure to +.BR free (3C) +the error message string in this situation. +.PP +In the case of an error, +.B hosts +is undefined. +In the case of success, +.B errmsg +is undefined. +.PP +On success +.B __pmUnparseHostSpec +returns a positive value indicating the number of characters written +into the supplied buffer. +However, if the supplied buffer was too small, a negative status code of +.B \-E2BIG +is returned. +.SH SEE ALSO +.BR pmcd (1), +.BR pmproxy (1), +.BR pmchart (1), +.BR __pmParseHostAttrsSpec (3), +.BR PMAPI (3) +and +.BR pmNewContext (3). diff --git a/man/man3/pmparseinterval.3 b/man/man3/pmparseinterval.3 new file mode 100644 index 0000000..cdf5009 --- /dev/null +++ b/man/man3/pmparseinterval.3 @@ -0,0 +1,90 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000-2004 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMPARSEINTERVAL 3 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmParseInterval\f1 \- convert interval string to \fBtimeval\fR structure +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.sp +.ad l +.hy 0 +.in +8n +.ti -8n +int pmParseInterval(const char *\fIstring\fP, struct timeval *\fIrslt\fP, char\ **\fIerrmsg\fP); +.sp +.in +.hy +.ad +cc ... \-lpcp +.ft 1 +.de CW +.ie t \f(CW\\$1\f1\\$2 +.el \fI\\$1\f1\\$2 +.. +.SH DESCRIPTION +.B pmParseInterval +parses the argument +.I string +specifying an interval of time and fills in the +.B tv_sec +and +.B tv_usec +components of the +.I rslt +structure to represent that interval. +.PP +The input +.I string +is most commonly the argument following a +.BR \-t +command line option to a PCP application, and +the syntax is fully described in +.BR PCPIntro (1). +.PP +.B pmParseInterval +returns 0 and +.I errmsg +is undefined if the parsing is successful. +.PP +If the given +.I string +does not conform to the required syntax +.B pmParseInterval +returns \-1 and a dynamically allocated +error message string in +.IR errmsg . +The error message +is terminated with a newline and +includes the text of the input +.I string +along with an indicator of the position at which the error was detected, +e.g. +.br +.in +1i +.CW "\&4minutes 30mumble" +.br +.CW "\& ^ -- unexpected value" +.in -1i +.PP +In the case of an error, the caller is responsible for calling +.BR free (3C) +to release the space allocated for +.IR errmsg . +.SH SEE ALSO +.BR PMAPI (3) +and +.BR pmParseTimeWindow (3). diff --git a/man/man3/pmparsemetricspec.3 b/man/man3/pmparsemetricspec.3 new file mode 100644 index 0000000..bec37fb --- /dev/null +++ b/man/man3/pmparsemetricspec.3 @@ -0,0 +1,115 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000-2004 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMPARSEMETRICSPEC 3 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmParseMetricSpec\f1, +\f3pmFreeMetricSpec\f1 \- uniform metric specification parser +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.sp +.ad l +.hy 0 +.in +8n +.ti -8n +int pmParseMetricSpec(const char *\fIstring\fP, int \fIisarch\fP, char\ *\fIsource\fP, pmMetricSpec\ **\fIrsltp\fP, char\ **\fIerrmsg\fP); +.br +.ti -8n +void pmFreeMetricSpec(pmMetricSpec *\fIrslt\fP); +.sp +.in +.hy +.ad +cc ... \-lpcp +.ft 1 +.SH DESCRIPTION +.B pmParseMetricSpec +accepts a +.B string +specifying the name of a PCP performance metric, and optionally +the source (either a hostname or a PCP archive log filename) +and instances for that metric. +The syntax is described in +.BR PCPIntro (1). +.PP +If neither \fBhost\fR nor \fBarchive\fR component +of the metric specification is provided, the \fBisarch\fR +and \fBsource\fR arguments are used to fill in the returned +.B pmMetricSpec +structure. +.PP +The +.B pmMetricSpec +structure that is returned via +.B rsltp +represents the parsed +.B string +and has the following +declaration: +.PP +.nf +.ft CW + typedef struct { + int isarch; /* source type: 0 -> live 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; +.fi +.PP +.B pmParseMetricSpec +returns 0 if the given +.B string +was successfully parsed. In this case all the storage allocated by +.B pmParseMetricSpec +can be released by a single call to +.BR free (3C) +using the address returned from +.B pmMetricSpec +via +.BR rsltp . +The convenience macro +.B pmFreeMetricSpec +is a thinly disguised wrapper for +.BR free (3C). +.PP +.B pmParseMetricSpec +returns +.B PM_ERR_GENERIC +and a dynamically allocated error message string in +.BR errmsg , +if the given +.B string +does not parse. Be sure to +.BR free (3C) +the error message string in this situation. +.PP +In the case of an error, +.B rsltp +is undefined. +In the case of success, +.B errmsg +is undefined. +If +.B "rsltp->ninst" +is 0, then +.B "rsltp->inst[0]" +is undefined. +.SH SEE ALSO +.BR PMAPI (3) +and +.BR pmLookupName (3). diff --git a/man/man3/pmparsetime.3 b/man/man3/pmparsetime.3 new file mode 100644 index 0000000..50bb598 --- /dev/null +++ b/man/man3/pmparsetime.3 @@ -0,0 +1,94 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000-2004 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMPARSETIME 3 "PCP" "Performance Co-Pilot" +.SH NAME +\f3__pmParseTime\f1 \- parse time point specification +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.br +#include <pcp/impl.h> +.sp +.ad l +.hy 0 +.in +8n +.ti -8n +int __pmParseTime(const char *\fIstring\fP, struct timeval *\fIlogStart\fP, struct\ timeval\ *\fIlogEnd\fP, struct\ timeval\ *\fIrslt\fP, char\ **\fIerrMsg\fP); +.sp +.in +.hy +.ad +cc ... \-lpcp +.ft 1 +.SH DESCRIPTION +.B __pmParseTime +is designed to encapsulate the interpretation of a time point specification in +command line switches for use by the PCP client tools. +.P +This function expects to be called with the time point specification as +.BR string . +If the tool is running against PCP archive(s), you also +need to supply the start time of the first (only) archive as +.BR logStart , +and the end of the last (only) archive as +.BR logEnd . +See +.BR pmGetArchiveLabel (3) +and +.BR pmGetArchiveEnd (3) +for how to obtain values for these parameters. +If the tool is running against a live feed of performance data, +.B logStart +should be the current time (but could be aligned on the next second +for example), while +.B logEnd +should have its tv_sec component set to INT_MAX. +.P +The +.B rslt +structure must be allocated before calling +.BR __pmParseTime . +.P +You also need to set the current PCP reporting time zone to correctly +reflect the \-z and \-Z command line parameters before calling +.BR __pmParseTime . +See +.BR pmUseZone (3) +and friends for information on how this is done. +.P +If the conversion is successful, +.B __pmParseTime +returns 0, and fills in +.B rslt +with the time value defined by the input +parameters. If the argument strings could not be parsed, it returns \-1 +and a dynamically allocated error message string in +.BR errMsg . +Be sure to +.BR free (3C) +this error message string. +.SH SEE ALSO +.BR PMAPI (3), +.BR pmGetArchiveEnd (3), +.BR pmGetArchiveLabel (3), +.BR pmNewContextZone (3), +.BR pmNewZone (3), +.BR pmParseInterval (3), +.BR pmParseTimeWindow (3), +.BR pmUseZone (3), +.BR __pmConvertTime (3) +and +.BR __pmParseCtime (3). diff --git a/man/man3/pmparsetimewindow.3 b/man/man3/pmparsetimewindow.3 new file mode 100644 index 0000000..3b8579e --- /dev/null +++ b/man/man3/pmparsetimewindow.3 @@ -0,0 +1,170 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000-2004 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMPARSETIMEWINDOW 3 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmParseTimeWindow\f1 \- parse time window command line arguments +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.sp +.ad l +.hy 0 +.in +8n +.ti -8n +int pmParseTimeWindow(const char *\fIswStart\fP, const\ char\ *\fIswEnd\fP, const\ char\ *\fIswAlign\fP, const\ char\ *\fIswOffset\fP, const\ struct\ timeval\ *\fIlogStart\fP, const\ struct\ timeval\ *\fIlogEnd\fP, struct\ timeval\ *\fIrsltStart\fP, struct\ timeval\ *\fIrsltEnd\fP, struct\ timeval\ *\fIrsltOffset\fP, char\ **\fIerrMsg\fP); +.sp +.in +.hy +.ad +cc ... \-lpcp +.ft 1 +.SH DESCRIPTION +.B pmParseTimeWindow +is designed to encapsulate the interpretation of the +.BR \-S , +.BR \-T , +.B \-A +and +.B \-O +command line options used by Performance Co-Pilot (PCP) applications +to define a time window of interest. +The time window is defined by a start time and an end time that constrains +the time interval during which the PCP application will retrieve and +display performance metrics. In the absence of the +.B \-O +and +.B \-A +options to specify an initial sample time origin +and time alignment (see below), the PCP application +will retrieve the first sample at the start of the time window. +.P +The syntax and meaning of the various argument formats for these options +is described in +.BR PCPIntro (1). +.SH USAGE +.B pmParseTimeWindow +expects to be called with the argument of the +.B \-S +option as +.BR swStart , +the argument of the +.B \-T +option as +.BR swEnd , +the argument of the +.B \-A +option as +.BR swAlign , +and the argument of the +.B \-O +option as +.BR swOffset . +Any or all of these parameters may be NULL +to indicate that the corresponding command line option was not +present. +.P +If the application is using a PCP archive log as the source +of performance metrics, you also +need to supply the time of the first archive log entry as +.BR logStart , +and the time of the last archive log entry as +.BR logEnd . +See +.BR pmGetArchiveLabel (3) +and +.BR pmGetArchiveEnd (3) +for how to obtain values for these times. +.P +If the application is manipulating multiple concurrent archive +logs, then the caller must resolve how the default time window +is to be defined (the union of the time intervals in all archive +logs is a likely interpretation). +.P +If the application is using a live feed of performance data, +.B logStart +should be the current time (but could be aligned on the next second +for example), while +.B logEnd +should have its +.I tv_sec +component set to +.BR INT_MAX . +.P +The +.BR rsltStart , +.B rsltEnd +and +.B rsltOffset +structures must be allocated before calling +.BR pmParseTimeWindow . +.P +You also need to set the current PCP reporting time zone to correctly +reflect the +.B \-z +and +.B \-Z +command line parameters before calling +.BR pmParseTimeWindow . +See +.BR pmUseZone (3) +and friends for information on how this is done. +.SH SEE ALSO +.BR PMAPI (3), +.BR pmGetArchiveEnd (3), +.BR pmGetArchiveLabel (3), +.BR pmNewContextZone (3), +.BR pmNewZone (3), +.BR pmParseInterval (3) +and +.BR pmUseZone (3). +.SH DIAGNOSTICS +If the conversion is successful, +.B pmParseTimeWindow +returns 1 and fills in +.BR rsltStart , +.B rsltEnd +and +.B rsltOffset +with the start, end, and offset times for the time window defined by the input +parameters. +The +.B errMsg +parameter is not changed when +.BR pmParseTimeWindow +returns 1. +.P +If the conversion is successful, but the requested alignment could not be +performed (e.g. the PCP archive log is too short) the alignment is +ignored, +.BR rsltStart , +.B rsltEnd +and +.B rsltOffset +are filled in and +.BR pmParseTimeWindow +returns 0. +In this case, +.B errMsg +will point to a warning message in an internal static buffer. +This buffer should not be freed. +.P +If the argument strings could not be parsed, +.B pmParseTimeWindow +returns \-1. +In this case, +.BR errMsg +will point to an error message +in a static internal buffer. diff --git a/man/man3/pmprintf.3 b/man/man3/pmprintf.3 new file mode 100644 index 0000000..6e707f4 --- /dev/null +++ b/man/man3/pmprintf.3 @@ -0,0 +1,104 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000-2004 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMPRINTF 3 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmprintf\f1, +\f3pmflush\f1 \- print formatted output in a window or to standard error +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.sp +int pmprintf(const char *\fIfmt\fP, ... /*\fIargs\fP*/); +.br +int pmflush(void); +.sp +cc ... \-lpcp +.ft 1 +.SH DESCRIPTION +The combination of +.B pmprintf +and +.B pmflush +produces output in either an +.BR xconfirm (1) +window, on the standard error stream, or to a file in a manner similar to +.BR fprintf (3). +The \f2fmt\f1 argument is used to control the conversion, formatting, and +printing of the variable length \f2args\f1 list. +The output technique is controlled via an environment variable. +.PP +.B pmprintf +appends the formatted message string to an internal buffer shared by the +two routines, without actually producing any output. +.PP +.B pmflush +causes the internal buffer to be either displayed in a window, printed +on standard error, or flushed to a file and the internal buffer to be cleared. +.PP +.SH ENVIRONMENT +The environment variable +.BR PCP_STDERR +controls the output technique used by \f3pmflush\f1: +.RS +4n +.PP +If +.B PCP_STDERR +is unset, the text is written onto the +.I stderr +stream of the caller. +.PP +If +.B PCP_STDERR +is set to the literal reserved word +.B DISPLAY +then the text will be displayed as a GUI dialog using +.BR xconfirm (1). +.PP +If +.B PCP_STDERR +is set to any other value then \f3pmflush\f1 +interprets the value as a file name and +appends the text to that file. The file is created if it doesn't already +exist, and in this case if the file creation fails, then +.I stderr +is used instead). +.RE +.SH FILES +.B pmprintf +uses the +.BR mkstemp (3) +function to create a temporary file. +This temporary file is deleted when +.B pmflush +is called. +.SH DIAGNOSTICS +On successful completion, \f3pmprintf\f1 returns the number of characters +transmitted, while +.B pmflush +returns a value of zero on successful completion. +.PP +For either routine, a negative value is returned if an error was encountered, +and this can be passed to +.BR pmErrStr (3) +to obtain the associated error message. +.PP +.SH SEE ALSO +.BR pmdbg (1), +.BR fprintf (3), +.BR mkstemp (3), +.BR pmErrStr (3) +and +.BR PMAPI (3). diff --git a/man/man3/pmprintvalue.3 b/man/man3/pmprintvalue.3 new file mode 100644 index 0000000..cf21db7 --- /dev/null +++ b/man/man3/pmprintvalue.3 @@ -0,0 +1,92 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000-2004 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMPRINTVALUE 3 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmPrintValue\f1 \- print a performance metric value +.SH "C SYNOPSIS" +.ft 3 +#include <stdio.h> +.br +#include <pcp/pmapi.h> +.sp +.ad l +.hy 0 +.in +8n +.ti -8n +void pmPrintValue(FILE *\fIf\fP, int \fIvalfmt\fP, int \fItype\fP, const\ pmValue\ *\fIval\fP, int\ \fIminwidth\fP); +.sp +.in +.hy +.ad +cc ... \-lpcp +.ft 1 +.SH DESCRIPTION +.de CW +.ie t \f(CW\\$1\f1\\$2 +.el \fI\\$1\f1\\$2 +.. +The value of a single performance metric (as identified by +.IR val ) +is printed on the standard I/O stream identified by +.IR f . +.PP +The value of the performance metric is interpreted according to the format of +.I val +as +defined by +.I valfmt +(from a +.CW pmValueSet +within a +.CW pmResult +structure; see +.BR pmFetch (3)) +and the generic description of the metrics type +passed in via +.IR type . +.PP +The value for +.I type +is typically extracted from a +.CW pmDesc +structure, following a call to +.BR pmLookupDesc (3) +for a particular performance metric. +.PP +The output will be optionally padded to be at least +.I minwidth +characters wide. +.PP +.B pmPrintValue +is most useful for displaying values of performance metrics from +.BR pmFetch (3) +(which returns a set of +.I valfmt +and +.I val +pairs for each requested metric), based upon the +metrics type as returned from +.BR pmLookupDesc (3). +.SH SEE ALSO +.BR PMAPI (3), +.BR pmAtomStr (3), +.BR pmConvScale (3), +.BR pmExtractValue (3), +.BR pmFetch (3), +.BR pmLookupDesc (3), +.BR pmTypeStr (3) +and +.BR pmUnitsStr (3). diff --git a/man/man3/pmreconnectcontext.3 b/man/man3/pmreconnectcontext.3 new file mode 100644 index 0000000..0b70948 --- /dev/null +++ b/man/man3/pmreconnectcontext.3 @@ -0,0 +1,131 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000-2004 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMRECONNECTCONTEXT 3 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmReconnectContext\f1 \- reconnect to a PMAPI context +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.sp +int pmReconnectContext(int \fIhandle\fP); +.sp +cc ... \-lpcp +.ft 1 +.SH DESCRIPTION +As a consequence of network, host or +Performance Metrics Collector Daemon (PMCD) failures, an applications +connection to a PMCD may be established and then subsequently lost. +.PP +The routine +.B pmReconnectContext +allows an application to request that the context identified by +.I handle +should be re-established, provided the associated PMCD is accessible. +.PP +To avoid flooding the system with reconnect requests, +.B pmReconnectContext +will only attempt a reconnection after a suitable delay from the previous +unsuccessful attempt to reconnect this context. This imposed restriction on +the reconnect re-try time interval uses an 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. +.PP +The environment variable +.B PMCD_RECONNECT_TIMEOUT +may be used to redefine the back-off intervals, see +.BR PMAPI (3). +.PP +If the reconnection succeeds, +.B pmReconnectContext +returns +.IR handle . +.PP +If +.I handle +identifies a context associated with an archive source of metrics, +.B pmReconnectContext +does nothing and returns +.IR handle . +.PP +Calling +.B pmReconnectContext +with a handle identifying a currently connected context will cause the +connection to be broken before any reconnection is attempted. +.PP +Note that even in the case of a successful reconnection, +.B pmReconnectContext +does not change the current +Performance Metrics Application Programming Interface (PMAPI) +context. +.PP +When attempting to connect to a remote +.BR pmcd (1) +on a machine that is booting, +.B pmReconnectContext +could potentially block for a long time until the remote machine +finishes its initialization. +.B pmReconnectContext +will 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 +.B PMCD_CONNECT_TIMEOUT +in the environment to a real number of seconds for the +desired timeout. +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. +.SH ENVIRONMENT +.TP +.B PMCD_CONNECT_TIMEOUT +Timeout period (in seconds) for +.BR pmcd (1) +connection attempts. +.TP +.B PMCD_RECONNECT_TIMEOUT +Redefines the back-off intervals - refer to +.BR PMAPI (3). +.SH SEE ALSO +.BR pmcd (1), +.BR PMAPI (3), +.BR pmNewContext (3) +and +.BR pmUseContext (3). +.SH DIAGNOSTICS +.P +.B PM_ERR_NOCONTEXT +.IP +.I handle +does not identify a valid PMAPI context +.P +.B \-ETIMEDOUT +.IP +The re-try time has not elapsed, or the reconnection is attempted and fails. +.SH CAVEAT +.P +Applications that use +.BR gethostbyname (3) +should exercise caution because the static fields in +.I "struct hostent" +may not be preserved across some +.BR PMAPI (3) +calls. +In particular, +.BR pmNewContext (3) +and +.BR pmReconnectContext (3) +both may call +.BR gethostbyname (3) +internally. diff --git a/man/man3/pmregisterderived.3 b/man/man3/pmregisterderived.3 new file mode 100644 index 0000000..f500754 --- /dev/null +++ b/man/man3/pmregisterderived.3 @@ -0,0 +1,421 @@ +'\"! tbl | mmdoc +'\"macro stdmacro +.\" +.\" Copyright (c) 2009 Ken McDonell. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMREGISTERDERIVED 3 "" "Performance Co-Pilot" +.SH NAME +\f3pmRegisterDerived\f1 \- register a derived metric name and definition +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.sp +char *pmRegisterDerived(char *\fIname\fP, char *\fIexpr\fP); +.sp +cc ... \-lpcp +.ft 1 +.SH DESCRIPTION +.PP +Derived metrics provide a way of extending the Performance Metrics +Name Space (PMNS) with new metrics defined at the PCP client-side using +arithmetic expressions over the existing performance metrics. +.PP +Typical uses would be to aggregate a number of similar metrics to provide +a higher-level summary metric or to support the ``delta V over delta V'' +class of metrics that are not possible in the base data semantics of PCP. +An example of the latter class would be the average I/O size, defined +as +.br +.ce +.ft CW +delta(disk.dev.total_bytes) / delta(disk.dev.total) +.ft R +where both of the +.ft CW +disk.dev +.ft R +metrics are counters, and what is required +is to to sample both metrics, compute the difference between the current +and previous values and then calculate the ratio of these differences. +.PP +The arguments to +.B pmRegisterDerived +are the +.I name +of the new derived metric and +.I expr +is an arithmetic expression defining how the values of +.I name +should be computed. +.PP +.I name +should follow the syntactic rules for the names of performance metrics, +namely one or more components separated with a dot (``.''), and each +component must begin with an alphabetic followed by zero or more characters +drawn from the alphabetics, numerics and underscore (``_''). +For more details, refer to +.BR PCPIntro (1) +and +.BR pmns (5). +.PP +.I name +must be unique across all derived metrics and should +.B not +match the +name of any regular metric in the PMNS. It is acceptable for +.I name +to share some part of its prefix with an existing subtree of the PMNS, +e.g. the average I/O size metric above could be named +.ft CW +disk.dev.avgsz +.ft R +which would place it amongst the other +.ft CW +disk.dev +.ft R +metrics in the PMNS. +Alternatively, derived metrics could populate their own subtree +of the PMNS, +e.g. the average I/O size metric above could be named +.ft CW +my.summary.disk.avgsz\c +.ft R +\&. +.PP +The expression +.I expr +follows these syntactic rules: +.IP * 2n +Terminal elements are either names of existing metrics or integer constants. +Recursive definitions are not allowed, so only the names of regular +metrics (not other derived metrics) may be used. Integer constants are +constrained to the precision of 32-bit unsigned integers. +.IP * 2n +The usual binary arithmetic operators are supported, namely \- addition (``+''), +subtraction (``-''), multiplication (``*'') and division (``/'') with +the normal precedence rules where multiplication and division have +higher precedence than addition and subtraction, so +.ft CW +a+b*c +.ft R +is evaluated as +.ft CW +a+(b*c)\c +.ft R +. +.IP * 2n +Parenthesis may be used for grouping. +.IP * 2n +The following unary functions operate on a single performance metric +and return one or more values. +For all functions (except +.ft CW +count()\c +.ft R +), the type of the operand metric must be arithmetic +(integer of various sizes and signedness, float or +double). +.TS +box,center; +cf(R) | cf(R)w(5i) +lf(CW) | lf(R). +Function Value +_ +avg(x) T{ +.fi +A singular instance being the average value across all instances for the metric x. +T} +_ +count(x) T{ +.fi +A singular instance being the count of the number of instances for the metric x. +T} +_ +delta(x) T{ +.fi +Returns the difference in values for the metric x between +one call to +.BR pmFetch (3) +and the next. There is one value in the result +for each instance that appears in both the current and the previous +sample. +T} +_ +rate(x) T{ +.fi +Returns the difference in values for the metric x between +one call to +.BR pmFetch (3) +and the next divided by the elapsed time between the calls to +.BR pmFetch (3). +The semantics of the derived metric are based on the semantics of the +operand (x) with the dimension in the +.B time +domain decreased by one and scaling if required in the time utilization case +where the operand is in units of time, and the derived metric is unitless. +This mimics the rate conversion applied to counter metrics by tools +such as +.BR pmval (1), +.BR pmie (1) +and +.BR pmchart (1). +There is one value in the result +for each instance that appears in both the current and the previous +sample. +T} +_ +max(x) T{ +.fi +A singular instance being the maximum value across all instances for the metric x. +T} +_ +min(x) T{ +.fi +A singular instance being the minimum value across all instances for the metric x. +T} +_ +sum(x) T{ +.fi +A singular instance being the sum of the values across all instances for the metric x. +T} +.TE +.IP * 2n +White space is ignored. +.PP +Syntactic checking is performed at the time +.B pmRegisterDerived +is called, but semantic checking is deferred until each new context +is created with +.BR pmNewContext (3) +or re-established with +.BR pmReconnectContext (3), +at which time the PMNS and metadata is available to +allow semantic checking and the metadata of the derived metrics +to be established. +.SH "SEMANTIC CHECKS AND RULES" +.PP +There are a number of conversions required to determine the +metadata for a derived metric and to ensure the semantics of +the expressions are sound. +.PP +In a binary expression, if the semantics of both operands is not +a counter (i.e. PM_SEM_INSTANT or PM_SEM_DISCRETE) then the result +will have semantics PM_SEM_INSTANT unless both operands are +PM_SEM_DISCRETE in which case the result is also PM_SEM_DISCRETE. +.PP +The mapping of the pmUnits of the metadata uses the following rules: +.IP * 2n +If both operands have a dimension of COUNT and the scales are not +the same, use the larger scale and convert the values of the operand +with the smaller scale. +.IP * 2n +If both operands have a dimension of TIME and the scales are not +the same, use the larger scale and convert the values of the operand +with the smaller scale. +.IP * 2n +If both operands have a dimension of SPACE and the scales are not +the same, use the larger scale and convert the values of the operand +with the smaller scale. +.IP * 2n +For addition and subtraction all dimensions for each of the operands +and result are identical. +.IP * 2n +For multiplication, the dimensions of the result are the sum of the +dimensions of the operands. +.IP * 2n +For division, the dimensions of the result are the difference of the +dimensions of the operands. +.PP +Scale conversion involves division if the dimension is positive else +multiplication if the dimension is negative. If scale conversion is +applied to either of the operands, the result is promoted to type +PM_TYPE_DOUBLE. +.PP +Putting all of this together in an example, consider the derived +metric defined as follows: +.br +.ad c +.ft CW +x = network.interface.speed - delta(network.interface.in.bytes) / delta(sample.milliseconds) +.ft R +.br +.ad l +The type, dimension and scale settings would propagate up the expression +tree as follows. +.TS +box,center; +cf(R) | cf(R) | cf(R) | cf(R) +lf(CW) | lf(CW) | lf(R) | lf(R). +Expression Type T{ +.fi +Dimension & Scale +T} T{ +.fi +Scale Factor(s) +T} +_ +sample.milliseconds DOUBLE millisec +delta(...) DOUBLE millisec +network...bytes U64 byte +delta(...) U64 byte +delta(...) / delta(...) DOUBLE byte/millisec T{ +.fi +/1048576 and *1000 +T} +network...speed FLOAT Mbyte/sec +x DOUBLE Mbyte/sec +.TE +.PP +Because semantic checking cannot be done at the time +.B pmRegisterDerived +is called, errors found during semantic checking are reported +using +.BR pmprintf (3). +These include: +.TP +Error: derived metric <name1>: operand: <name2>: <reason> +There was a problem calling +.BR pmLookupName (3) +to identify the operand metric <name2> used in the definition +of the derived metric <name1>. +.TP +Error: derived metric <name1>: operand (<name2> [<pmid2>]): <reason> +There was a problem calling +.BR pmLookupDesc (3) +to identify the operand metric <name2> with PMID <pmid2> +used in the definition of the derived metric <name1>. +.TP +Semantic error: derived metric <name>: <operand> <op> <operand>: Illegal operator for counters +If both operands have the semantics of counter, only addition or subtraction +make sense, so multiplication and division are not allowed. +.TP +Semantic error: derived metric <name>: <operand> <op> <operand>: Illegal operator for counter and non-counter +Only multiplication or division are allowed if the left operand has the +semantics of a counter and the right operand is +.B not +a counter. +.TP +Semantic error: derived metric <name>: <operand> <op> <operand>: Illegal operator for non-counter and counter +Only multiplication is allowed if the right operand has the +semantics of a counter and the left operand is +.B not +a counter. +.TP +Semantic error: derived metric <name>: <operand> <op> <operand>: Non-arithmetic type for <left-or-right> operand +The binary arithmetic operators are only allowed with operands with an +arithmetic type (integer of various sizes and signedness, float or +double). +.TP +Semantic error: derived metric <name>: <function>(<operand>): Non-arithmetic operand for function +The unary functions are only defined if the operand has arithmetic type. +.TP +Semantic error: derived metric <name>: Incorrect time dimension for operand +Rate conversion using the +.BR rate () +function is only possible for operand metrics with a Time dimension of 0 or 1 +(see +.BR pmLookupDesc (3)). +If the operand metric's Time dimension is 0, then +the derived metrics has a value "per second" (Time dimension of -1). +If the operand metric's Time dimension is 1, then +the derived metrics has a value of time utilization (Time dimension of 0). +.SH "EXPRESSION EVALUATION" +For the binary arithmetic operators, +if either operand must be scaled (e.g. convert bytes to Kbytes) then the +result is promoted to PM_TYPE_DOUBLE. +Otherwise the type of the result is determined +by the types of the operands, as per the following table which is evaluated +from top to bottom until a match is found. +.TS +box,center; +cf(R) | cf(R) | cf(R) +lf(R) | lf(R) | lf(R). +Operand Types Operator Result Type +_ +either is PM_TYPE_DOUBLE any PM_TYPE_DOUBLE +_ +any division PM_TYPE_DOUBLE +_ +either is PM_TYPE_FLOAT any PM_TYPE_FLOAT +_ +either is PM_TYPE_U64 any PM_TYPE_U64 +_ +either is PM_TYPE_64 any PM_TYPE_64 +_ +either is PM_TYPE_U32 any PM_TYPE_U32 +_ +T{ +.fi +otherwise (both are PM_TYPE_32) +T} any PM_TYPE_32 +.TE +.SH CAVEATS +.PP +Unary negation is not supported, so the following expressions would be +syntactically incorrect, +.ft CW +\-3*abc +.ft R +and +.ft CW +\-this.number\c +.ft R +. +.PP +Derived metrics are not available when using +.BR pmFetchArchive (3) +as this routine does not use a target list of PMIDs that could be +remapped (as is done for +.BR pmFetch (3)). +.PP +.B pmRegisterDerived +does not apply retrospectively to any open contexts, so the normal +use would be to make all calls to +.B pmRegisterDerived +(possibly via +.BR pmLoadDerivedConfig (3)) +and then call +.BR pmNewContext (3). +.PP +There is no +.B pmUnregisterDerived +method, so once registered a derived metric persists for the life +of the application. +.SH DIAGNOSTICS +.PP +On success, +.B pmRegisterDerived +returns NULL. +.PP +If a syntactic error is found at the time of registration, the +value returned by +.B pmRegisterDerived +is a pointer into +.I expr +indicating +.B where +the error was found. To identify +.B what +the error was, the application should call +.BR pmDerivedErrStr (3) +to retrieve the corresponding parser error message. +.SH SEE ALSO +.BR PCPIntro (1), +.BR PMAPI (3), +.BR pmDerivedErrStr (3), +.BR pmFetch (3), +.BR pmLoadDerivedConfig (3), +.BR pmNewContext (3) +and +.BR pmReconnectContext (3). diff --git a/man/man3/pmsetmode.3 b/man/man3/pmsetmode.3 new file mode 100644 index 0000000..7b47281 --- /dev/null +++ b/man/man3/pmsetmode.3 @@ -0,0 +1,258 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000-2004 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMSETMODE 3 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmSetMode\f1 \- set collection time parameters for the current PMAPI context +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.sp +int pmSetMode(int \fImode\fP, const struct timeval *\fIwhen\fP, int \fIdelta\fP); +.sp +cc ... \-lpcp +.ft 1 +.SH DESCRIPTION +.de CW +.ie t \f(CW\\$1\f1\\$2 +.el \fI\\$1\f1\\$2 +.. +.B pmSetMode +is used to define the collection time and/or mode for accessing +performance metrics and meta-data in the current +Performance Metrics Application Programming Interface (PMAPI) +context. +This mode affects the semantics of subsequent calls to the following +PMAPI routines: +.BR pmFetch (3), +.BR pmFetchArchive (3), +.BR pmLookupDesc (3), +.BR pmGetInDom (3), +.BR pmLookupInDom (3) +and +.BR pmNameInDom (3). +.PP +If +.I mode +is +.B PM_MODE_LIVE +then all information is returned from the active pool of performance metrics +as of the time that the PMAPI call is made, and the other two parameters to +.B pmSetMode +are ignored. +.B PM_MODE_LIVE +is the default mode when a new PMAPI context of type +.B PM_CONTEXT_HOST +is created. +.PP +If the +.I mode +is not +.BR PM_MODE_LIVE , +then the +.I when +parameter defines a time origin, and all requests for meta-data (metric +descriptions and instance identifiers from the instance domains) will be +processed to reflect the state of the meta-data as of the time origin, i.e. we +use the last state of this information at, or before, the time origin. +.PP +If the +.I mode +is +.B PM_MODE_INTERP +then, in the case of +.BR pmFetch (3), +the underlying code will use an interpolation scheme to compute the values of +the metrics from the values recorded for times in the proximity of the time +origin. +A +.I mode +of +.B PM_MODE_INTERP +may only be used with an archive context. +.PP +If the +.I mode +is +.B PM_MODE_FORW +then, in the case of +.BR pmFetch (3), +the collection of recorded metric values will be scanned in a forwards +direction in time, until values for at least one of the requested metrics is +located after the time origin, and then all requested metrics stored in the log +or archive at that time will be returned with the corresponding timestamp. +A +.I mode +of +.B PM_MODE_FORW +may only be used with an archive context. +.PP +If the +.I mode +is +.B PM_MODE_BACK +then, the situation is the same as for +.BR PM_MODE_FORW , +except a +.BR pmFetch (3) +will be serviced by scanning the collection of recorded metrics in a backwards +direction in time for metrics before the time origin. +A +.I mode +of +.B PM_MODE_BACK +may only be used with an archive context. +.PP +If the +.I mode +is +.B PM_MODE_FORW +or +.BR PM_MODE_BACK , +and no qualifying metrics can be found in the requested direction of searching +before the end or start of the archive +log is found, then +.BR pmFetch (3) +returns the special error indicator, +.BR PM_ERR_EOL . +.PP +For +.IR mode s +other than +.BR PM_MODE_LIVE , +after each successful +.BR pmFetch (3), +the time origin is reset to the timestamp returned via the +.CW pmResult +structure from +.BR pmFetch (3). +.PP +The +.B pmSetMode +parameter +.I delta +defines an additional number of time units that should be used to adjust the +time origin (forwards or backwards), after the new time origin from the +.CW pmResult +has been determined. +This automatic adjustment of the time origin only occurs when the +.I mode +is +.BR PM_MODE_INTERP , +and the adjustment is applied, even if the +.BR pmFetch (3) +fails because the time origin is outside the range defined by +the records in an archive log, i.e. returns +.BR PM_ERR_EOL . +The high-order bits of the +.I mode +parameter is also used to optionally set the units of time for the +.I delta +field. To specify the units of time use +.B PM_XTB_SET +macro with one of the values +.BR PM_TIME_NSEC , +.BR PM_TIME_MSEC , +.BR PM_TIME_SEC , +etc. +as follows: +.P +.in +0.5i +PM_MODE_INTERP | PM_XTB_SET(PM_TIME_XXXX) +.P +If no units are specified the default is to interpret +.I delta +as milliseconds. +.PP +Using these +.I mode +options, an application can implement replay, playback, fast forward, reverse, +etc. for performance metric values held in the archive log by alternating calls +to +.B pmSetMode +and +.BR pmFetch (3). +.PP +As a special case, if +.I when +is +.B NULL +then the +.I mode +and +.I delta +arguments are used as described above, but the current time in the archive +is not altered. +.PP +For example, the following code fragment may be used to dump just those values +recorded in an archive in correct temporal sequence, for a selected set of +performance metrics; this uses the default collection time mechanisms. +.PP +.ft CW +.nf +.in +0.5i +pmNewContext(PM_CONTEXT_ARCHIVE, "myarchive"); +while (pmFetch(npmid, pmidlist, &result) != PM_ERR_EOL) { + /* + * process real metric values as of result->timestamp + */ + \&. . . + pmFreeResult(result); +} +.in +.fi +.ft 1 +.PP +Alternatively, to replay interpolated metrics from the log in reverse +chronological order, at 10 second intervals (of recorded time), the following +code fragment could be used. +.PP +.ft CW +.nf +.in +0.5i +struct timeval mytime; + +mytime.tv_sec = 0x7fffffff; +pmSetMode(PM_MODE_BACK, &mytime, 0); +pmFetchArchive(&result); +mytime = result->timestamp; +pmFreeResult(result); +pmSetMode(PM_MODE_INTERP | PM_XTB_SET(PM_TIME_SEC), &mytime, \-10); + +while (pmFetch(numpmid, pmidlist, &result) != PM_ERR_EOL) { + /* + * process interpolated metric values as of + * result->timestamp + */ + \&. . . + pmFreeResult(result); +} +.in +.fi +.ft 1 +.SH "SEE ALSO" +.BR PMAPI (3), +.BR pmFetch (3), +.BR pmFetchArchive (3), +.BR pmGetInDom (3), +.BR pmLookupDesc (3), +.BR pmLookupInDom (3) +and +.BR pmNameInDom (3). +.SH DIAGNOSTICS +.IP \f3PM_ERR_MODE\f1 +The +.I mode +parameter is invalid diff --git a/man/man3/pmsortinstances.3 b/man/man3/pmsortinstances.3 new file mode 100644 index 0000000..bec71fd --- /dev/null +++ b/man/man3/pmsortinstances.3 @@ -0,0 +1,49 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000-2004 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMSORTINSTANCES 3 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmSortInstances\f1 \- sort performance metric values on instance identifier +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.sp +void pmSortInstances(pmResult *\fIresult\fP); +.sp +cc ... \-lpcp +.ft 1 +.SH DESCRIPTION +.de CW +.ie t \f(CW\\$1\f1\\$2 +.el \fI\\$1\f1\\$2 +.. +.PP +The routine +.B pmSortInstances +may be used to guarantee that for each performance metric in the +.I result +from +.BR pmFetch (3), +the instances are in ascending instance identifier sequence. +.PP +This is most useful when trying to compute rates from two consecutive +.BR pmFetch (3) +results. +.SH SEE ALSO +.BR PMAPI (3) +and +.BR pmFetch (3). +.SH DIAGNOSTICS +None. diff --git a/man/man3/pmspeclocalpmda.3 b/man/man3/pmspeclocalpmda.3 new file mode 100644 index 0000000..e5f82bb --- /dev/null +++ b/man/man3/pmspeclocalpmda.3 @@ -0,0 +1,118 @@ +'\"macro stdmacro +.TH PMSPECLOCALPMDA 3 "" "Performance Co-Pilot" +.SH NAME +\f3__pmSpecLocalPMDA\f1 \- process command-line argument for the table of DSO PMDAs +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.br +#include <pcp/impl.h> +.sp +char *__pmSpecLocalPMDA(const char *\fIspec\fP); +.sp +cc ... \-lpcp +.ft 1 +.SH DESCRIPTION +PCP contexts of type +.B PM_CONTEXT_LOCAL +are used by clients that wish to fetch metrics directly from one or more PMDAs on +the local host without involving +.BR pmcd (1). +.PP +.B __pmSpecLocalPMDA +provides a convenience wrapper to be used by applications that wish +to use a command line argument (usually with +.BR -K ) +to control the DSO PMDAs that are available for a +.B PM_CONTEXT_LOCAL +context. +.PP +The +.I spec +argument specifies actions for one or more DSO PMDAs using up to four fields separated by commas +(``,''), namely: +.PD 0 +.TP 3n +.IP \- +an opcode with one of the values +.B add +(add a new entry), +.B del +(delete an existing entry) or +.B clear +(clear all entries from the table). +.IP \- +the PMDA's domain number +.IP \- +the path to the PMDA DSO (may +be absolute or relative to the $PCP_VAR_DIR/pmdas directory and +the DSO suffix is optional), and +.IP \- +the +name of the PMDA's initialization routine. +.PD +.PP +All fields are required to add a new entry. To delete an entry the opcode +is required plus either or both of the domain number and path fields. +To clear all entries, only the opcode is required. +.PP +If +.I spec +is parsed successfully, then +.BR __pmLocalPMDA (3) +is called with the extracted arguments. +.SH "RETURN VALUE" +On success, +.B __pmSpecLocalPMDA +will return NULL. +.PP +On error or failure, +.B __pmSpecLocalPMDA +will return a pointer to a static error message. +.SH EXAMPLES +Some examples of valid +.I spec +strings: +.TP +.ft CW +clear +.ft +Delete all entries from the DSO table. +.TP +.ft CW +add,123,foo/foo_pmda,foo_init +.ft +Add the ``foo'' PMDA using domain 123. +The PMDA's DSO is most likely in below the directory +.B $PCP_PMDAS_DIR +and named +.I foo/foo_pmda.so +(for ELF-style platforms) +or +.I foo/foo_pmda.dylib +(for BSD-style platforms) +or +.I foo\\foo_pmda.dll +(for Windows-style platforms). +The initialization routine for the ``foo'' PMDA is +.IR foo_init (). +.TP +.ft CW +del,123 +Delete the entry for the DSO with domain 123. +.TP +.ft CW +del,,foo/foo_pmda +Delete the entry with a pathname to the DSO that matches +.IR foo/foo_pmda . +.TP +.ft CW +del,123,foo/foo_pmda +Delete the entry for the DSO with either domain 123 +and/or a pathname to the DSO that matches +.IR foo/foo_pmda . +.SH SEE ALSO +.BR PMAPI (3), +.BR __pmLocalPMDA (3) +and +.BR pmNewContext (3). diff --git a/man/man3/pmstore.3 b/man/man3/pmstore.3 new file mode 100644 index 0000000..6370385 --- /dev/null +++ b/man/man3/pmstore.3 @@ -0,0 +1,104 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000-2004 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMSTORE 3 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmStore\f1 \- modify values of performance metrics +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.sp +.nf +int pmStore(const pmResult *\fIresult\fP); +.fi +.sp +cc ... \-lpcp +.ft 1 +.SH DESCRIPTION +.de CW +.ie t \f(CW\\$1\f1\\$2 +.el \fI\\$1\f1\\$2 +.. +In some special cases it may be helpful to modify the current values of +performance metrics, +e.g. to reset a counter to zero, or to modify a ``metric'' which is a control +variable for some agent collecting performance metrics. +.PP +The routine +.B pmStore +is a lightweight inverse of +.BR pmFetch (3). +.PP +The caller must build the +.CW pmResult +data structure (of course, this could have been returned from an earlier +.BR pmFetch (3) +call) and then call +.BR pmStore . +.PP +It is an error to pass a request to +.B pmStore +in which the +.CW numval +field within any of the +.B pmValueSet +structure has a value less than one. +.PP +The current +Performance Metrics Application Programming Interface (PMAPI) +context must be one with a host as the source of metrics, and the +current value of the nominated metrics will be changed, i.e. +.B pmStore +cannot be used to make retrospective changes to information in either +the archive logs, or in the recent past for real-time sources of metrics. +.PP +The return code from +.B pmStore +is zero for success. +.SH SEE ALSO +.BR PMAPI (3), +.BR pmFetch (3) +and +.BR pmSetMode (3). +.SH DIAGNOSTICS +.IP \f3PM_ERR_GENERIC\f1 +At least one of the modifications was rejected. +No other status is available +from below the PMAPI (this is the lightweight part of the functionality!). In +cases where the outcome of +.B pmStore +for individual metrics is important, the caller should make one call to +.B pmStore +for each metric. On the other hand, a bulk modification can be performed in a +single +.B pmStore +call for situations in which the outcome is not critical. +.IP \f3PM_ERR_NOTHOST\f1 +The current PMAPI context is an archive rather than a host, or it +is a host that is not set to the current time, i.e. has been ``rewound'' +to the recent past using +.BR pmSetMode (3). +.IP \f3PM_ERR_TOOSMALL\f1 +The number of metrics specified in +.I result +is less than one. +.IP \f3PM_ERR_VALUE\f1 +One or more of the +.CW pmValueSet s +in +.I result +has a +.CW numval +field with a value less than one. diff --git a/man/man3/pmtime.3 b/man/man3/pmtime.3 new file mode 100644 index 0000000..900ea16 --- /dev/null +++ b/man/man3/pmtime.3 @@ -0,0 +1,181 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2009 Aconex. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMTIME 3 "Aconex" "Performance Co-Pilot" +.SH NAME +\f3pmtime\f1, +\f3pmTimeConnect\f1, +\f3pmTimeDisconnect\f1, +\f3pmTimeRecv\f1, +\f3pmTimeSendAck\f1, +\f3pmTimeShowDialog\f1 \- +time control functions for synchronizing the archive position and +update interval between one or more applications +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmtime.h> +.sp +int pmTimeConnect(int \fIport\fP, pmTime *\fIstate\fP); +.br +int pmTimeDisconnect(int \fIfd\fP); +.br +int pmTimeSendAck(int \fIfd\fP, struct timeval *\fIfetchTime\fP); +.br +int pmTimeShowDialog(int \fIfd\fP, int \fIshow\fP); +.br +int pmTimeRecv(int \fIfd\fP, pmTime *\fIstate\fP); +.sp +cc ... \-lpcp_gui +.ft 1 +.SH DESCRIPTION +These functions form part of the Performance Metrics Applications +Programming Interface (PMAPI) and are intended to provide a uniform +mechanism for applications to both replay archive data and report +live data in a time synchronized manner. +.PP +The +.I pmTime +structure has the following fields: +.sp 0.5v +.ft CW +.nf +.in +0.25i +typedef struct { + unsigned int magic; + unsigned int length; + pm_tctl_command command; + pm_tctl_source source; + pm_tctl_state state; + pm_tctl_mode mode; + struct timeval delta; + struct timeval position; + struct timeval start; /* archive only */ + struct timeval end; /* archive only */ + char data[0]; /* arbitrary length info (TZ) */ +} pmTime; +.in -0.25i +.fi +.ft R +.PP +In the simplest case, the application should call +.B pmTimeConnect +to connect to the time control server, +.BR pmtime (1), +and then repeatedly call +.B pmTimeRecv +in the main loop of the application. +On success, +.B pmTimeConnect +returns a non-negative file descriptor. +In applications which have multiple threads of control, rather than +simply blocking in +.BR pmTimeRecv , +the file descriptor may be used in calls to +.BR select (2). +In graphical applications, the file descriptor may be used to interface +with the event loop. +.PP +The +.I port +parameter to +.B pmTimeConnect +is the port number of the socket on which the time control server is +(or will be) listening for new connections. +.PP +The state parameter to +.B pmTimeConnect +is used to initialize a new time control server or to pass additional +information to an existing time control server. +The +.I start +and +.I finish +fields indicate the chronological bounds interesting to the application. +The +.I showdialog +field indicates whether the time control server should initially show +or hide the dialog. +The +.IR position , +.IR delta, +and +.I data +fields indicate the initial archive position, update interval, +time zone string and time zone label string. +.PP +.B pmTimeRecv +blocks until the time control server sends a command message. +It then updates the state parameter and returns one of the PM_TCTL +command identifiers. +.PP +The PM_TCTL_SET command indicates the application should seek to the +archive position (see +.BR pmSetMode (3)) +returned in the position field of the state parameter. +.PP +The PM_TCTL_STEP command indicates the application should perform an +update, i.e. advance (or rewind, if delta is negative) to the time +indicated by position and then fetch new metric values, update the +display or whatever. In order for several application to remain +synchronized, the time control server will wait until all applications +have acknowledged that they have completed the step command. +Applications should call pmTimeSendAck when the step command has been +processed. Note that PM_TCTL_STEP is the only command that requires an +explicit acknowledgement. +.PP +The PM_TCTL_VCRMODE command is used by the time control server to +indicate the current VCR mode. +.PP +The value is returned in the vcrmode field of the state parameter passed +to +.BR pmTimeRecv , +and remains valid until the next PM_TCTL_VCRMODE command is received. +.PP +The PM_TCTL_TZ command indicates the application should use a new time- +zone, as indicated in the +.I tz +and +.I tzlabel +fields of the state parameter. +.PP +The PM_TCTL_BOUNDS command is sent to all applications when the time +control server changes its chronological bounds. +This may occur when a new application connects to the time control +server or the user changes the bounds manually. +Most applications will ignore this command. +.PP +The PM_TCTL_SHOWDIALOG command will be sent to all applications when the +visibility of the time control server changes. +This allows applications to alter the text in menus or buttons to +reflect this change. +Applications may change the visibility of the time control dialog using +the +.B pmTimeShowDialog +function. +The initial visibility is determined when +the time control dialog is first created by an application calling +.B pmTimeConnect +with the showdialog field in the state parameter set to the desired value. +.PP +The +.B pmTimeDisconnect +function may be used to close the command socket to the time control server. +This is useful when applications need to change the connection mode, +e.g. to divorce the current time control server and connect to a new one. +.SH SEE ALSO +.BR pmtime (1), +.BR PMAPI (3) +and +.BR pmSetMode (3). diff --git a/man/man3/pmtraversepmns.3 b/man/man3/pmtraversepmns.3 new file mode 100644 index 0000000..21ee276 --- /dev/null +++ b/man/man3/pmtraversepmns.3 @@ -0,0 +1,110 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000-2004 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMTRAVERSEPMNS 3 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmTraversePMNS\f1, +\f3pmTraversePMNS_r\f1 \- traverse the performance metrics name space +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.sp +.nf +int pmTraversePMNS(const char *\fIname\fP, void (*\fIdometric\fP)(const char *)); +int pmTraversePMNS_r(const char *\fIname\fP, void (*\fIdometric_r\fP)(const char *, void *), void *\fIclosure\fP); +.fi +.sp +cc ... \-lpcp +.ft 1 +.SH DESCRIPTION +.de CW +.ie t \f(CW\\$1\f1\\$2 +.el \fI\\$1\f1\\$2 +.. +.PP +The routine +.B pmTraversePMNS +may be used to perform a depth-first traversal of the Performance +Metrics Name Space (PMNS). +.PP +The traversal starts at the node identified by +.I name +\- if +.I name +is an empty string (i.e. \f3""\f1), the traversal starts at the +root of the PMNS. +Usually +.I name +would be the pathname of a non-leaf node in the PMNS. +.PP +For each leaf node (i.e. performance metric) found in the traversal, +the user-supplied routine +.I dometric +is called with the full pathname of that metric in the PMNS as +the single argument. +This argument is null-byte terminated, and is +constructed from a buffer that is managed internally to +.BR pmTraversePMNS . +Consequently the value is only valid during the call to +.I dometric +\- if the pathname needs to be retained, it should be copied using +.BR strdup (3C) +before returning from +.IR dometric . +.PP +The +.B pmTraversePMNS_r +routine performs the same function, except the callback method +.I func_r +has an additional parameter that will be +.I closure +from the initial call to +.BR pmTraversePMNS_r . +The additional parameter to +.B pmTraversePMNS_r +and the callback method allows the caller to pass context +through +.B pmTraversePMNS_r +and into the callback method +.IR func_r , +making the service more useful for multi-threaded applications +where thread-private data can be accessed in the callback method +via the +.I closure +argument. +.PP +On success +.B pmTraversePMNS +returns the number of children of +.IR name , +which may be zero. +.SH SEE ALSO +.BR PMAPI (3) +and +.BR pmGetChildren (3). +.SH DIAGNOSTICS +.IP \f3PM_ERR_NOPMNS\f1 +Failed to access a PMNS for operation. +Note that if the application hasn't a priori called pmLoadNameSpace(3) +and wants to use the distributed PMNS, then a call to +.B pmTraversePMNS +must be made inside a current context. +.IP \f3PM_ERR_NAME\f1 +The initial pathname +.I name +is not valid in the current PMNS. +.IP \f3PM_ERR_*\f1 +Other diagnostics are for protocol failures when +accessing the distributed PMNS. diff --git a/man/man3/pmtrimnamespace.3 b/man/man3/pmtrimnamespace.3 new file mode 100644 index 0000000..01a743d --- /dev/null +++ b/man/man3/pmtrimnamespace.3 @@ -0,0 +1,100 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000-2004 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMTRIMNAMESPACE 3 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmTrimNameSpace\f1 \- prune a performance metrics name space +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.sp +int pmTrimNameSpace(void); +.sp +cc ... \-lpcp +.ft 1 +.SH DESCRIPTION +If the current +Performance Metrics Application Programming Interface (PMAPI) +context +corresponds to a version 1 archive log of Performance Co-Pilot (PCP) +performance metrics (as collected +by +.BR pmlogger (1) +.BR -V1 ), +then the currently loaded +Performance Metrics Name Space (PMNS), is trimmed to exclude +metrics for which no description can +be found in the archive. +The PMNS is further trimmed to remove empty subtrees that do not contain any +performance metric. +.PP +Since PCP archives usually contain some subset +of all metrics named in the default PMNS, +.B pmTrimNameSpace +effectively trims the application's PMNS to contain only the +names of the metrics in the archive. +.PP +Since PCP 2.0, +.B pmTrimNameSpace +is only needed for dealing with version 1 archives. +Version 2 archives actually store the "trimmed" PMNS. +.PP +Prior to any trimming, +the PMNS is restored to the state as of the completion of the last +.BR pmLoadASCIINameSpace (3) +or +.BR pmLoadNameSpace (3), +so the effects of consecutive calls to +.B pmTrimNameSpace +with archive contexts are +.B not +additive. +.PP +If the current PMAPI context +corresponds to a host +and a +.BR pmLoadASCIINameSpace (3) +or +.BR pmLoadNameSpace (3) +call was made, +then the PMNS reverts to all names loaded into the PMNS +at the completion of the last +.BR pmLoadASCIINameSpace (3) +or +.BR pmLoadNameSpace (3), +i.e. any trimming is undone. +.PP +On success, +.B pmTrimNameSpace +returns zero. +.SH SEE ALSO +.BR pmlogger (1), +.BR PMAPI (3), +.BR pmLoadASCIINameSpace (3), +.BR pmLoadNameSpace (3), +.BR pmNewContext (3) +and +.BR pmns (5). +.SH DIAGNOSTICS +.IP \f3PM_ERR_NOPMNS\f1 +you must have loaded a PMNS using +.BR pmLoadASCIINameSpace (3) +or +.BR pmLoadNameSpace (3) +before calling +.B pmTrimNameSpace +.IP \f3PM_ERR_NOCONTEXT\f1 +the current PMAPI context +is invalid diff --git a/man/man3/pmtypestr.3 b/man/man3/pmtypestr.3 new file mode 100644 index 0000000..4d86d4b --- /dev/null +++ b/man/man3/pmtypestr.3 @@ -0,0 +1,93 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000-2004 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMTYPESTR 3 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmTypeStr\f1, +\f3pmTypeStr_r\f1 \- convert a performance metric type into a string +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.sp +const char *pmTypeStr(int \fItype\fP); +.br +char *pmTypeStr_r(int \fItype\fP, char *\fIbuf\fP, int \fIbuflen\fP); +.sp +cc ... \-lpcp +.ft 1 +.SH DESCRIPTION +.de CW +.ie t \f(CW\\$1\f1\\$2 +.el \fI\\$1\f1\\$2 +.. +Given a performance metric +.IR type , +.B pmTypeStr +produces a terse ASCII equivalent, appropriate for use in error and diagnostic +messages. +The +.B pmTypeStr_r +function does the same, but stores the result in a user-supplied buffer +.I buf +of length +.IR buflen , +which should have room for at least 20 bytes. +.PP +The value for +.I type +is typically extracted from a +.CW pmDesc +structure, following a call to +.BR pmLookupDesc (3) +for a particular performance metric. +.PP +Examples are +.B 32 +(for +.I type +equals +.BR PM_TYPE_32 ), +.B U64 +(for +.I type +equals +.BR PM_TYPE_U64 ), +.B AGGREGATE +(for +.I type +equals +.BR PM_TYPE_AGGREGATE ), +etc. +.PP +The string value result for +.B pmTypeStr +is held in a single static buffer, so the returned value is +only valid until the next call to +.BR pmTypeStr . +.SH NOTES +.B pmTypeStr +returns a pointer to a static buffer and hence is not thread-safe. +Multi-threaded applications should use +.B pmTypeStr_r +instead. +.SH SEE ALSO +.BR PMAPI (3), +.BR pmAtomStr (3), +.BR pmConvScale (3), +.BR pmExtractValue (3), +.BR pmLookupDesc (3), +.BR pmPrintValue (3) +and +.BR pmUnitsStr (3). diff --git a/man/man3/pmunitsstr.3 b/man/man3/pmunitsstr.3 new file mode 100644 index 0000000..9a38bd1 --- /dev/null +++ b/man/man3/pmunitsstr.3 @@ -0,0 +1,91 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000-2004 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMUNITSSTR 3 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmUnitsStr\f1, +\f3pmUnitsStr_r \- convert a performance metric's units into a string +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.sp +const char *pmUnitsStr(const pmUnits *\fIpu\fP); +.br +char *pmUnitsStr_r(const pmUnits *\fIpu\fP, char *\fIbuf\fP, int \fIbuflen\fP); +.sp +cc ... \-lpcp +.ft 1 +.SH DESCRIPTION +.de CW +.ie t \f(CW\\$1\f1\\$2 +.el \fI\\$1\f1\\$2 +.. +The encoding of a performance metric's dimensionality and scale uses +a +.CW pmUnits +structure; see +.BR pmLookupDesc (3). +.PP +As an aid to labeling graphs and tables, or for error messages, +.B pmUnitsStr +will take a dimension and scale specification as per +.IR pu , +and return the +corresponding text string. +The +.B pmUnitsStr_r +function does the same, but stores the result in a user-supplied buffer +.I buf +of length +.IR buflen , +which should have room for at least 60 bytes. +.PP +For example +.CW "{1, -2, 0, PM_SPACE_MBYTE, PM_TIME_SEC, 0}" , +as the value of +.I *pu +gives the result string +.CW "Mbyte / sec^2" . +.PP +The string value result from +.B pmUnitsStr +is held in a single static buffer, so the returned value is +only valid until the next call to +.BR pmUnitsStr . +.PP +If the ``count'' dimension is non-zero, and the ``count'' scale is not +zero, then the text string will +include a decimal scaling factor, eg. +.CW "count x 10^6" . +.PP +As a special case, if all components of the dimension are zero, then the +``count'' scale is used to produce the text. If this scale is zero the +result is an empty string, otherwise the result is of the form +.CW "x1 0^2" . +.SH NOTES +.B pmUnitsStr +returns a pointer to a static buffer and hence is not thread-safe. +Multi-threaded applications should use +.B pmUnitsStr_r +instead. +.SH SEE ALSO +.BR PMAPI (3), +.BR pmAtomStr (3), +.BR pmConvScale (3), +.BR pmExtractValue (3), +.BR pmLookupDesc (3), +.BR pmPrintValue (3) +and +.BR pmTypeStr (3). diff --git a/man/man3/pmunloadnamespace.3 b/man/man3/pmunloadnamespace.3 new file mode 100644 index 0000000..96af920 --- /dev/null +++ b/man/man3/pmunloadnamespace.3 @@ -0,0 +1,48 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000-2004 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMUNLOADNAMESPACE 3 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmUnloadNameSpace\f1 \- unload a local performance metrics name space for an application +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.sp +void pmUnloadNameSpace(void); +.sp +cc ... \-lpcp +.ft 1 +.SH DESCRIPTION +If one has previously loaded a local Name Space using +.BR pmLoadNameSpace (3) +or +.BR pmLoadASCIINameSpace (3), +then calling +.BR pmUnloadNameSpace (3) +will free up the memory associated with the Name Space and force all +subsequent PMNS routine calls to use the distributed PMNS. +If +.BR pmUnloadNameSpace (3) +is called before calling +.BR pmLoadNameSpace (3) +or +.BR pmLoadASCIINameSpace (3), +then it will effectively do nothing. +.SH SEE ALSO +.BR PMAPI (3), +.BR pmLoadASCIINameSpace (3), +.BR pmLoadNameSpace (3) +and +.BR pmns (5). diff --git a/man/man3/pmunpackeventrecords.3 b/man/man3/pmunpackeventrecords.3 new file mode 100644 index 0000000..6f581ad --- /dev/null +++ b/man/man3/pmunpackeventrecords.3 @@ -0,0 +1,165 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2014 Red Hat. +.\" Copyright (c) 2010 Ken McDonell. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMUNPACKEVENTRECORDS 3 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmUnpackEventRecords\f1 \- unpack event records +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.sp +int pmUnpackEventRecords(pmValueSet *\fIvsp\fP, int \fIidx\fP, pmResult ***\fIrap\fP); +.sp +int pmUnpackHighResEventRecords(pmValueSet *\fIvsp\fP, int \fIidx\fP, pmHighResResult ***\fIhrap\fP); +.sp +cc ... \-lpcp +.ft 1 +.SH DESCRIPTION +.de CW +.ie t \f(CW\\$1\f1\\$2 +.el \fI\\$1\f1\\$2 +.. +Event records are encoded as a packed array of records within a +.I pmResult +using a container metric with a value of type +.B PM_TYPE_EVENT , +and a +.I pmHighResResult +when using a metric of type +.BR PM_TYPE_HIGHRES_EVENT . +.PP +.B pmUnpackEventRecords +and +.B pmUnpackHighResEventRecords +may be used to unpack event records from a metric value +identified by +.I vsp +and +.IR idx . +If the metric has a singular value, +.I idx +should be 0, else the ordinal instance value identified by +.I idx +will be unpacked, i.e. vsp->vlist[idx]. +The unpacked records are turned into either +.I pmResult +or +.I pmHighResResult +structures, one per event record and one metric per event parameter, and +.I rap +is returned as a pointer to an array (NULL pointer terminated) of +pointers to the result structures. +.PP +The only difference between the two result types is the timestamp scale; +the +.I pmHighResResult +allows for nanosecond precision, whereas +.I pmResult +allows for microsecond resolution. +.PP +Some control information from the packed event records is unpacked +into additional ``anonymous'' metrics as follows: +.TP 4n +1. +If the event record has a non-zero flags value, then the corresponding +.IR pmResult / pmHighResResult +will have the flags value encoded with the additional metric +.B event.flags +that is inserted ahead of all other event parameters. +.TP 4n +2. +If the event record flag is set to +.BR PM_EVENT_FLAG_MISSED , +then the corresponding +.IR pmResult / pmHighResResult +will have one metric +.B event.missed +with a value that equals the number of event records ``missed'' because +either the PMDA could not keep up, or the PMAPI client did not collect +the event records fast enough. +.PP +.B pmUnpackEventRecords +returns the number of +.I pmResult +structures as the return value, which is >= 0 for success. +Similarly, +.B pmUnpackHighResEventRecords +returns the number of +.I pmHighResResult +structures as the return value, which is >= 0 for success. +.PP +.I rap +and the associated +.I pmResult +structures may be freed using the convenience function +.BR pmFreeEventResult (3). +.PP +Similarly, the +.I hrap +and the associated +.I pmHighResResult +structures may be freed using the convenience function +.BR pmFreeHighResEventResult . +.SH "RETURN VALUE" +The following errors are possible: +.TP 10n +PM_ERR_CONV +The values associated with +.I vsp +are not encoded using the format PM_VAL_DPTR or PM_VAL_SPTR, or +the flags at the head of the event record has an unexpected value. +.TP 10n +PM_ERR_INST +The value associated with +.I vsp +is not singular as expected. +.TP 10n +PM_ERR_TYPE +.I vsp +is not a value of type +.BR PM_TYPE_EVENT . +.TP 10n +PM_ERR_TOOSMALL +The value identified by +.I vbp +is not legal because the value length is less than the minimum size, +or the number of event records encoded in the (value header) +.IR pmEventArray / pmEventHighResArray +structure is negative, or the number of missed event records in the +array is negative. +.TP 10n +PM_ERR_TOOBIG +Either +.B vsp +indicates more than one value is present (all the event records +are expected to be packed in a single metric value), or +when unpacking the event records, the processing continues past the end of +the enclosing value. Indicates corruption of the packed event record. +.TP 10n +PM_ERR_TYPE +Event parameters must have one of the arithmetic types, else +.BR PM_TYPE_AGGREGATE , +.B PM_TYPE_STRING +or +.BR PM_TYPE_AGGREGATE_STATIC . +.TP 10n +other values < 0 +refer to +.BR pmErrStr (3). +.SH SEE ALSO +.BR PMAPI (3) +and +.BR pmFreeEventResult (3). diff --git a/man/man3/pmusecontext.3 b/man/man3/pmusecontext.3 new file mode 100644 index 0000000..5571b02 --- /dev/null +++ b/man/man3/pmusecontext.3 @@ -0,0 +1,65 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000-2004 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMUSECONTEXT 3 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmUseContext\f1 \- change current PMAPI context +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.sp +int pmUseContext(int \fIhandle\fP); +.sp +cc ... \-lpcp +.ft 1 +.SH DESCRIPTION +An application using the +Performance Metrics Application Programming Interface (PMAPI) +may manipulate several concurrent contexts, +each associated with a source of performance metrics, e.g. \c +.BR pmcd (1) +on some host, or an archive log of performance metrics as created by +.BR pmlogger (1). +.PP +Calling +.B pmUseContext +causes the +current PMAPI context to be set to +the context identified by +.IR handle . +The value of +.I handle +must be one returned from an earlier call to +.BR pmNewContext (3) +or +.BR pmDupContext (3). +.PP +Below the PMAPI, all contexts used by an application are saved in their most +recently modified state, so +.B pmUseContext +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. +.SH SEE ALSO +.BR PMAPI (3), +.BR pmDestroyContext (3), +.BR pmDupContext (3), +.BR pmNewContext (3) +and +.BR pmWhichContext (3). +.SH DIAGNOSTICS +.B PM_ERR_NOCONTEXT +.IP +.I handle +does not identify a valid PMAPI context diff --git a/man/man3/pmusezone.3 b/man/man3/pmusezone.3 new file mode 100644 index 0000000..c5ef0b9 --- /dev/null +++ b/man/man3/pmusezone.3 @@ -0,0 +1,53 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000-2004 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMUSEZONE 3 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmUseZone\f1 \- re-establish a reporting timezone +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.sp +int pmUseZone(const int \fItz_handle\fP); +.sp +cc ... \-lpcp +.ft 1 +.SH DESCRIPTION +The current reporting timezone effects the timezone used by +.BR pmCtime (3) +and +.BR pmLocaltime (3). +.PP +The argument +.I tz_handle +identifies a reporting timezone as previously established by +a call to +.BR pmNewZone (3) +or +.BR pmNewContextZone (3), +and this becomes +the current reporting timezone. +.SH SEE ALSO +.BR PMAPI (3), +.BR pmCtime (3), +.BR pmLocaltime (3), +.BR pmNewContextZone (3), +.BR pmNewZone (3) +and +.BR pmWhichZone (3). +.SH DIAGNOSTICS +A return value less than zero indicates the value of +.I tz_handle +is not legal. diff --git a/man/man3/pmwebapi.3 b/man/man3/pmwebapi.3 new file mode 100644 index 0000000..e4ad6f4 --- /dev/null +++ b/man/man3/pmwebapi.3 @@ -0,0 +1,252 @@ +'\" t macro stdmacro +.\" +.\" Copyright (c) 2013-2014 Red Hat, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMWEBAPI 3 "PCP" "Performance Co-Pilot" +.SH NAME +\f3PMWEBAPI\f1 \- introduction to the Performance Metrics Web Application Programming Interface + +.de SAMPLE +.br +.RS +.nf +.nh +.. +.de ESAMPLE +.hy +.fi +.RE +.. + +.SH OVERVIEW + +The PMWEBAPI interface is a binding of a subset of the PMAPI to the +web. It uses HTTP as transport, REST as organizational style for +request/parameter encoding (the GET and POST methods are +interchangeable), and JSON as response encoding. A context identifier +is used as a persistent way to refer to PMAPI contexts across related +web requests. These context identifiers expire after a configurable +period of disuse. Errors generally result in HTTP-level error responses. +An +.nh +.B Access-Control-Allow-Origin: * +.hy +header is added to all JSON responses. + +.SH CONTEXT CREATION: pmNewContext + +To create a new web context identifier, a web client invokes: +.TP +.B /pmapi/context?local=ANYTHING +Creates a PM_CONTEXT_LOCAL PMAPI context. +.TP +.B /pmapi/context?hostname=STRING +.TP +.B /pmapi/context?hostspec=STRING +Creates a PM_CONTEXT_HOST PMAPI context with the given host name and/or extended +specification. If the host specification contains a userid/password combination, +then the corresponding pmapi context operations will require HTTP Basic authentication +credentials with matching userid/password. +.TP +.B /pmapi/context?archivefile=ARCHIVE +Creates a PM_CONTEXT_ARCHIVE PMAPI context with the given file name. +.PP +In addition, the web client may add the parameter +.B &polltimeout=MMMM +for a maximum interval (in seconds) between expected accesses to the +given context. This value is limited by pmwebd configuration, and is +a courtesy to allow pmwebd to free up memory earlier in case of sudden +web application shutdown. + +If successful, the response from these requests is a JSON document of the form: + +.SAMPLE +{ "context" : NNNNN } +.ESAMPLE + +The number (a 32-bit unsigned decimal) is then used in all later operations. + +.SH PMAPI OPERATIONS + +The general form of the requests is as follows: +.B /pmapi/NNNNN/OPERATION +where +.TP +.B /pmapi +is the fixed prefix for all PMWEBAPI operations, +.TP +.B NNNNN +is a PMWEBAPI context number returned from a context-creation call, or +assigned permanently at pmwebd startup, and +.TP +.B OPERATION?PARAM1=VALUE2&PARAM2=VALUE2 +identifies the operation and its URL-encoded parameters. Some +parameters may be optional. + +.SS METRIC METADATA: pmLookupName, pmLookupDesc, pmTraversePMNS_r + +The general form of the requests is as follows: +.TP +.B /pmapi/NNNNN/_metric +Traverse the entire PMNS. +.TP +.B /pmapi/NNNNN/_metric?prefix=NAME +Traverse the subtree of PMNS with the prefix NAME. +.PP +The response is a JSON document that provides the metric metadata +as an array. For example: + +.SAMPLE +{ "metrics": [ + { "name":"foo.bar", "pmID":PPPP, "indom":DDDD, + "type":"32", "sem":"instant", "units":"MHz", + "text-oneline":"foo bar", "text-help":"blah blah blah" }, + { "name":"foo.bar2", ... } + ... + ] } +.ESAMPLE + +Most of the fields are self-explanatory. +.TP +PPPP +the PMID +.TP +DDDD +the instance domain +.TP +type +from pmTypeStr +.TP +units +from pmUnitsStr +.TP +sem +an abbreviation of the metric semantic: +.TS +l l. +PM_SEM_COUNTER "counter" +PM_SEM_INSTANT "instant" +PM_SEM_DISCRETE "discrete" +.TE + +.SS METRIC VALUE: pmFetch + +The general form of the requests is as follows: +.TP +.B /pmapi/NNNNN/_fetch?names=NAME1,NAME2 +Fetch current values for given named metrics. +.TP +.B /pmapi/NNNNN/_fetch?pmids=PPPP1,PPPP2 +Fetch current values for given PMIDs. +.PP +The response is a JSON document that provides the values for +all requested metrics, for all their instances. + +.SAMPLE +{ "timestamp": { "s":SEC, "us":USEC }, + "values": [ + { "pmid":PPPP1, "name":"NAME1", + "instances:" [ + { "instance":IIII1, "value":VALUE1 } + { "instance":IIII2, "value":VALUE2 } + ... + ] }, + { "pmid":PPPP2, "name":"NAME2", ... } + ... + ] } +.ESAMPLE + +Most of the fields are self-explanatory. Numeric metric types +are represented as JSON integer or floating-point values. Strings +are passed verbatim, except that non-ASCII values are replaced +with a Unicode 0xFFFD REPLACEMENT CHARACTER code. Event type metrics +are not currently supported. + +.SS INSTANCE DOMAINS METADATA: pmGetInDom, pmNameInDom, pmLookupInDom + +The general form of the requests is as follows: +.TP +.B /pmapi/NNNN/_indom?indom=DDDD +List instances of the given instance domain. +.TP +.B /pmapi/NNNN/_indom?name=NAME +List instances of the instance domain belonging to the named metric. +.PP +In addition, either query may be suffixed with: +.TP +.B &instance=IIII,JJJJ +Restrict listings to given instance code numbers. +.TP +.B &iname=INAME1,INAME2 +Restrict listings to given instance names. +.PP + +The response is a JSON document that provides the metric metadata +as an array. For example: + +.SAMPLE +{ "indom":DDDD, + "instances": [ + { "instance":IIII, "name":"INAME" } + ... + ] } +.ESAMPLE + +.SS INSTANCE PROFILE: pmAddProfile, pmDelProfile + +.TP +.B /pmapi/NNNN/_profile_reset? +These are not currently supported. +.TP +.B /pmapi/NNNN/_profile_reset?indom=DDDD +These are not currently supported. +.TP +.B /pmapi/NNNN/_profile_add?indom=DDDD&instance=IIII,JJJJ +These are not currently supported. +.TP +.B /pmapi/NNNN/_profile_add?indom=DDDD&iname=IIII,JJJJ +These are not currently supported. +.TP +.B /pmapi/NNNN/_profile_del?indom=DDDD&instance=JJJJ +These are not currently supported. +.TP +.B /pmapi/NNNN/_profile_del?indom=DDDD&iname=INAME1,INAME2 +These are not currently supported. + +.SS DERIVED METRICS: pmRegisterDerived + +.TP +.B /pmapi/NNNNN/_derive?name=NAME&expr=EXPRESSION +These are not currently supported. + +.SS CONTEXT COPY: pmDupContext + +.TP +.B /pmapi/NNNNN/copy +These are not currently supported. + +.SS CONTEXT CLOSE: pmDestroyContext + +.TP +.B /pmapi/NNNNN/destroy +This is not likely to be supported, as it is destructive and would offer +a tempting target to brute-force attackers. Instead, the pmwebd timeout +is used to automatically free unused contexts. + +.SH SEE ALSO +.BR PCPIntro (1), +.BR PCPIntro (3), +.BR pmwebd (3), +and +.BR PMAPI (3) diff --git a/man/man3/pmwhichcontext.3 b/man/man3/pmwhichcontext.3 new file mode 100644 index 0000000..36c229d --- /dev/null +++ b/man/man3/pmwhichcontext.3 @@ -0,0 +1,49 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000-2004 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMWHICHCONTEXT 3 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmWhichContext\f1 \- identify the current PMAPI context +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.sp +int pmWhichContext(void); +.sp +cc ... \-lpcp +.ft 1 +.SH DESCRIPTION +An application using the +Performance Metrics Application Programming Interface (PMAPI) +may manipulate several concurrent contexts, +each associated with a source of performance metrics, e.g. \c +.BR pmcd (1) +on some host, or an archive log of performance metrics as created by +.BR pmlogger (1). +.PP +.B pmWhichContext +returns a handle for the current PMAPI context, that may +be used in the associated PMAPI routines that require a handle +to identify a PMAPI context. +.SH SEE ALSO +.BR PMAPI (3), +.BR pmDestroyContext (3), +.BR pmDupContext (3), +.BR pmNewContext (3) +and +.BR pmUseContext (3). +.SH DIAGNOSTICS +.IP \f3PM_ERR_NOCONTEXT\f1 +no current context diff --git a/man/man3/pmwhichzone.3 b/man/man3/pmwhichzone.3 new file mode 100644 index 0000000..01be747 --- /dev/null +++ b/man/man3/pmwhichzone.3 @@ -0,0 +1,53 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000-2004 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMWHICHZONE 3 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmWhichZone\f1 \- return current reporting timezone +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.sp +int pmWhichZone(char **\fItz\fP); +.sp +cc ... \-lpcp +.ft 1 +.SH DESCRIPTION +The current reporting timezone effects the timezone used by +.BR pmCtime (3) +and +.BR pmLocaltime (3). +.PP +.B pmWhichZone +returns the handle of the current timezone, +as previously established by +a call to +.BR pmNewZone (3) +or +.BR pmNewContextZone (3). +If the call is successful (i.e. there exists a current reporting timezone) +then a non-negative integer is returned and +.I tz +is set to point to a static buffer containing the timezone string itself. +.SH SEE ALSO +.BR PMAPI (3), +.BR pmCtime (3), +.BR pmLocaltime (3), +.BR pmNewContextZone (3), +.BR pmNewZone (3) +and +.BR pmUseZone (3). +.SH DIAGNOSTICS +A return value less than zero indicates there is no current reporting timezone. diff --git a/man/man5/GNUmakefile b/man/man5/GNUmakefile new file mode 100644 index 0000000..4470193 --- /dev/null +++ b/man/man5/GNUmakefile @@ -0,0 +1,30 @@ +# +# Copyright (c) 2014 Red Hat. +# Copyright (c) 2000,2004 Silicon Graphics, Inc. All Rights Reserved. +# +# This program is free software; you can redistribute it and/or modify it +# under the terms of the GNU General Public License as published by the +# Free Software Foundation; either version 2 of the License, or (at your +# option) any later version. +# +# This program is distributed in the hope that it will be useful, but +# WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +# or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +# for more details. +# + +TOPDIR = ../.. +include $(TOPDIR)/src/include/builddefs +-include ./GNUlocaldefs + +MAN_SECTION = 5 +MAN_PAGES = $(shell echo *.5) +MAN_DEST = $(PCP_MAN_DIR)/man$(MAN_SECTION) +LSRCFILES = $(MAN_PAGES) + +default_pcp default : $(MAN_PAGES) + +include $(BUILDRULES) + +install install_pcp : default + @$(INSTALL_MAN) diff --git a/man/man5/mmv.5 b/man/man5/mmv.5 new file mode 100644 index 0000000..79e763c --- /dev/null +++ b/man/man5/mmv.5 @@ -0,0 +1,202 @@ +'\"! tbl | nroff \-man +'\"macro stdmacro +.\" +.\" Copyright (c) 2009 Max Matveev +.\" Copyright (c) 2009 Aconex. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH MMV 5 "" "Performance Co-Pilot" +.SH NAME +\f3mmv\f1 \- Memory Mapped Values for Performance Co-Pilot +.SH SYNOPSIS +.I $PCP_TMP_DIR/mmv/<file> +.SH DESCRIPTION +The files in \f2$PCP_TMP_DIR/mmv\f1 are generated by +\f2mmv_stats_init\f1() function from \f3libpcp_mmv\f1 library. There could +be multiple files in this directory, each file representing a single source +of the performance metrics. The metrics are harvested by the \f2mmv\f1 PMDA +which exports them to the rest of the Performance Co-Pilot infrastructure. +.SH FILE FORMAT +Each file starts with the following header: +.TS +box,center; +c | c | c +n | n | l. +Offset Length Name +_ +0 4 tag == "MMV\\0" +_ +4 4 Version +_ +8 8 Generation 1 +_ +16 8 Generation 2 +_ +24 4 Number of TOC entries +_ +28 4 Flags +_ +32 4 Process identifier (PID) +_ +36 4 Cluster identifier +.TE +.PP +.PP +The generation numbers are timestamps at the time of file +creation, and must match for the file to be considered by +the MMV PMDA. +.PP +The flags can specify ways in which the client would like +the MMV PMDA to behave - e.g. the MMV_FLAG_PROCESS flag +specifies that only if the process identified by PID is +currently running should those values be exported. +.PP +Finally, if set, the cluster identifier is a hint to the MMV +PMDA as to what cluster should be used with this application +when forming the individual metric identifiers. +A performance metric identifier (see \f2PMDA\f1(3)) consists of +the PMDA domain number, the cluster number, and the individual +item numbers described in the Metrics section. +.PP +The header is followed by at least 2 TOC sections: +one section for metrics and another for values. +The TOC section has the following format: +.TS +box,center; +c | c | c +n | n | l. +Offset Length Value +_ +0 4 Section Type (see \f2mmv_stats.h\f1) +_ +4 4 Number of entries in the section +_ +8 8 Section's offset from the start of the file +.TE +.PP +.PP +The section types are: +.IP +1: +Indoms (instance domain definitions) +.IP +2: +Instances +.IP +3: +Metrics (metric definitions) +.IP +4: +Values +.IP +5: +String +.PP +The only mandatory sections are Metrics and Values. +Indoms and Instances sections only appear if there are metrics with +multiple instances. +String sections only appear if there are metrics with string values, +or when Metrics or Indoms are defined with help text. +.PP +The entries in the Indoms section have the following format: +.TS +box,center; +c | c | c +n | n | l. +Offset Length Value +_ +0 4 Unique serial number for this domain +_ +4 4 Number of entries in the domain +_ +8 8 Offset to first instance +_ +16 8 Short help text offset +_ +24 8 Long help text offset +.TE +.PP +.PP +The entries in the Instances section have the following format: +.TS +box,center; +c | c | c +n | n | l. +Offset Length Value +_ +0 8 Offset into the indom section +_ +8 4 Unused padding (zero filled) +_ +12 4 Internal instance identifier +_ +16 64 External instance identifier +.TE +.PP +.PP +The entries in the Metrics section have the following format: +.TS +box,center; +c | c | c +n | n | l. +Offset Length Value +_ +0 64 Metric Name +_ +64 4 Metric Item (see \f2PMDA\f1(3)) +_ +68 4 Metric Type (see \f2mmv_stats.h\f1) +_ +72 4 Semantics (see \f2PMAPI\f1(3)) +_ +76 4 Dimensions (see \f2PMAPI\f1(3)) +_ +80 4 Instance Domain ID +_ +84 4 Unused padding (zero filled) +_ +88 8 Short help text offset +_ +96 8 Long help text offset +.TE +.PP +.PP +The entries in the Values section have the following format: +.TS +box,center; +c | c | c +n | n | l. +Offset Length Value +_ +0 8 \f3pmAtomValue\f1 (see \f2PMAPI\f1(3)) +_ +8 8 Extra space for STRING and ELAPSED +_ +16 8 Offset into the Metrics section +_ +24 8 Offset into the Instances section +.TE +.PP +.PP +Each entry in the strings section is a 256 byte character array, +containing a single NULL-terminated character string. +So each string has a maximum length of 256 bytes, which includes +the terminating NULL. +.PP +.SH SEE ALSO +.BR PCPIntro (1), +.BR PMAPI (3), +.BR mmv_stats_init (3), +.BR pcp.conf (5) +and +.BR pcp.env (5). diff --git a/man/man5/pcp-archive.5 b/man/man5/pcp-archive.5 new file mode 100644 index 0000000..f27547d --- /dev/null +++ b/man/man5/pcp-archive.5 @@ -0,0 +1,348 @@ +'\"! tbl | nroff \-man +'\"macro stdmacro +.\" +.\" Copyright (c) 2014 Red Hat Inc. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PCP-ARCHIVE 5 "" "Performance Co-Pilot" + +.SH NAME +\f3pcp-archive\f1 \- Archive Files for Performance Co-Pilot + +.SH SYNOPSIS + +.I $PCP_LOG_DIR/pmlogger/*/*.{meta,index,0} + +.I $PCP_LOG_DIR/pmmgr/*/*.{meta,index,0} + +.SH DESCRIPTION + +PCP log archives store volumes of historical values of arbitrary +Performance Co-Pilot metrics recorded from a single host. Archives +are self-contained in the sense that they contain all the important +metadata that would be required for off-line or off-site analysis. +The format is intended to be stable in order to allow long-term +historical storage and processing by current tools. (Compatibility +in the other direction \- new files, old tools \- is not as fully +assured.) +.PP +Archives may be read by most PCP client tools, using the +.IR "\-a ARCHIVE" +option, or dumped raw by +.BR pmdumplog (1). +Archives may be created by +.BR pmlogger (1) +and bulk-import tools. +Archives may be merged, analyzed, and subsampled using specialized +tools such as +.BR pmlogsummary "(1), " pmlogreduce "(1), " pmlogrewrite "(1), and " pmlogextract (1). +In addition, PCP archives may be grouped together into PCP "archive folios", +which are managed by the +.BR pmafm (1) +tool. +.PP +PCP archives consist of several physical files that share a common arbitrary prefix, +e.g., +.IR myarchive . +.TP +myarchive.0, myarchive.1, ... +Metric values. May grow rapidly. +.TP +myarchive.meta +Information for PMAPI functions such as +.IR pmLookupDesc "(3) and " pmGetInDom (3). +May grow in fits and spurts, as logged instances and instance domains vary. +.TP +myarchive.index +A temporal index, mapping timestamps to offsets in the other files. +Grows slowly. + +.SH COMMON FEATURES + +All three types of files have a similar record-based structure, a +convention of network-byte-order (big-endian) encoding, and 32-bit +fields for tagging/padding for those records. Strings are stored as +8-bit characters without assuming a specific encoding, so normally +ASCII. See also the +.BR __pmLog* +types in +.IR include/pcp/impl.h . + +.SS RECORD FRAMING +.PP +The volume and meta files are divided into self-identifying records. +.TS +box,center; +c | c | c +c | c | l. +Offset Length Name +_ +0 4 N, length of record, in bytes, including this field +4 N-8 record payload, usually starting with a 32-bit tag +N-4 4 N, length of record (again) +.TE + +.SS ARCHIVE LOG LABEL +All three types of files begin with a "log label" header, which +identifies the host name, the time interval covered, and a time zone. +.TS +box,center; +c | c | c +c | c | l. +Offset Length Name +_ +0 4 tag, PM_LOG_MAGIC | PM_LOG_VERS02=0x50052602 +4 4 pid of pmlogger process that wrote file +8 4 log start time, seconds part (past UNIX epoch) +12 4 log start time, microseconds part +16 4 current log volume number (or \-1=.meta, \-2=.index) +20 64 name of collection host +80 40 time zone string ($TZ environment variable) +.TE +.PP +All fields, except for the current log volume number field, match for +all archive-related files produced by a single run of the tool. + +.SH ARCHIVE VOLUME (.0, .1, ...) RECORDS + +.SS pmResult + +After the archive log label record, an archive volume file contains +metric values corresponding to the +.IR pmResult +set of one +.IR pmFetch +operation, which is almost identical to the form on disk. The record +size may vary according to number of PMIDs being fetched, the number +of instances for their domains. File size is limited to 2GB, due to +storage of 32-bit offsets within the .index file. +.TS +box,center; +c | c | c +c | c | l. +Offset Length Name +_ +0 4 timestamp, seconds part (past UNIX epoch) +4 4 timestamp, microseconds part +8 4 number of PMIDs with data following +12 M pmValueSet #0 +12+M N pmValueSet #1 +12+M+N ... ... +NOP X pmValueBlock #0 +NOP+X Y pmValueBlock #1 +NOP+X+Y ... ... +.TE +.PP +Records with a number-of-PMIDs equal to zero are "markers", and may +represent interruptions, missing data, or time discontinuities in +logging. + +.SS pmValueSet + +This subrecord represents the measurements for one metric. + +.TS +box,center; +c | c | c +c | c | l. +Offset Length Name +_ +0 4 PMID +4 4 number of values +8 4 storage mode, PM_VAL_INSITU=0 or PM_VAL_DPTR=1 +12 M pmValue #0 +12+M N pmValue #1 +12+M+N ... ... +.TE + +.PP +The metric-description metadata for PMIDs is found in the .meta files. +These entries are not timestamped, so the metadata is assumed to be +unchanging throughout the archiving session. + +.SS pmValue + +This subrecord represents one measurement for one instance of the metric. +It is a variant type, depending on the parent pmValueSet's value-format +field. This allows small numbers to be encoded compactly, but retain +flexibility for larger or variable-length data to be stored later in the +pmResult record. + +.TS +box,center; +c | c | c +c | c | l. +Offset Length Name +_ +0 4 number in instance-domain (or PM_IN_NULL=-1) +4 4 value (INSITU) \fIor\fR + offset in pmResult to our pmValueBlock (DPTR) +.TE + +.PP +The instance-domain metadata for PMIDs is found in the .meta files. +Since the numeric mappings may change during the lifetime of the +logging session, it is important to match up the timestamp of the +measurement record with the corresponding instance-domain record. +That is, the instance-domain corresponding to a measurement at time T +are the records with largest timestamps T' <= T. + +.SS pmValueBlock + +Instances of this subrecord are placed at the end of the +.IR pmValueSet , +after all the +.IR pmValue +subrecords. Iff needed, they are padded at the end to the next-higher +32-bit boundary. + +.TS +box,center; +c | c | c +c | c | l. +Offset Length Name +_ +0 1 value type (same as \fIpmDesc.type\fR) +1 3 4 + N, the length of the subrecord +4 N bytes that make up the raw value +4+N 0-3 padding (not included in the 4+N length field) +.TE + +Note that for +.IR PM_TYPE_STRING , +the length includes an explicit NUL terminator byte. +For +.IR PM_TYPE_EVENT , +the value bytestring is further structured. + +.SS pmEventArray + +.IR (TBD) + +.SH METADATA FILE (.meta) RECORDS + +After the archive log label record, the metadata file contains +interleaved metric-description and timestamped instance-domain +descriptors. File size is limited to 2GB, due to storage of 32-bit +offsets within the .index file. Unlike the archive volumes, these +records are not forced to 32-bit alignment! See also +.IR src/libpcp/src/logmeta.c . + +.SS pmDesc + +Instances of this record represent the metric description, giving a +name, type, instance-domain identifier, and a set of names to each +PMID used in the archive volume. + +.TS +box,center; +c | c | c +c | c | l. +Offset Length Name +_ +0 4 tag, TYPE_DESC=1 +4 4 pmid +8 4 type (PM_TYPE_*) +12 4 instance domain number +16 4 semantics of value (PM_SEM_*) +20 4 units: bit-packed pmUnits +4 4 number of alternative names for this PMID +28 4 N: number of bytes in this name +32 N bytes of the name, no NUL terminator nor padding +32+N 4 N2: number of bytes in next name +36+N N2 bytes of the name, no NUL terminator nor padding +\... ... ... +.TE + +.SS pmLogIndom + +Instances of this record represent the number-string mapping table of +an instance domain. The instance domain number will have already been +mentioned in a prior +.IR pmDesc +record. Since new instances may appear over a long archiving run, these +records are timestamped, and must be searched when decoding +.IR pmResult +records from the main archive volumes. Instance names may be reused +between instance numbers, so an offset-based string table is used that +could permit sharing. + +.TS +box,center; +c | c | c +c | c | l. +Offset Length Name +_ +0 4 tag, TYPE_INDOM=2 +4 4 timestamp, seconds part (past UNIX epoch) +8 4 timestamp, microseconds part +12 4 instance domain number +16 4 N: number of instances in domain, normally >0 +20 4 first instance number +24 4 first offset into string table (see below) +28 4 second instance number (if appropriate) +32 4 second offset into string table (etc.) +\... ... ... +20+8*N M base of string table, containing + packed, NUL-terminated instance names +.TE +.PP +Records of this form \fIreplace\fR the existing instance-domain: prior +records are not searched for resolving instance numbers in measurements +after this timestamp. + +.SH INDEX FILE (.index) RECORDS + +After the archive log label record, the temporal index file contains a +plainly concatenated, unframed group of tuples, which relate timestamps to +32-bit seek offsets in the volume and meta files. (This limits those +files to 2GB in size.) These records are fixed-size, fixed-format, +and are \fInot\fR enclosed in the standard length/payload/length +wrapper: they just take up the entire remainder of the .index file. +See also +.IR src/libpcp/src/logutil.c . + +.TS +box,center; +c | c | c +c | c | l. +Offset Length Name +_ +0 4 event time, seconds part (past UNIX epoch) +4 4 event time, microseconds part +8 4 archive volume number (0...N) +12 4 byte offset in .meta file of pmDesc or pmLogIndom +16 4 byte offset in archive volume file of pmResult +.TE + +Since temporal indexes are optional, and exist only to speed up +time-wise random access of metrics and their metadata, index records +are emitted only intermittently. An archive reader program should not +presume any particular rate of data flow into the index. However, +common events that may trigger a new temporal-index record include +changes in instance-domains, switching over to a new archive volume, +just starting or stopping logging. One reliable invariant however is +that, for each index entry, there are to be no meta or archive-volume +records with a timestamp after that in the index, but physically +before the byte-offset in the index. + +.PP +.SH SEE ALSO +.BR PCPIntro (1), +.BR PMAPI (3), +.BR pmlogger (1), +.BR pmdumplog (1), +.BR pmafm (1), +.BR pcp.conf (5), +and +.BR pcp.env (5). diff --git a/man/man5/pcp.conf.5 b/man/man5/pcp.conf.5 new file mode 100644 index 0000000..be29c2d --- /dev/null +++ b/man/man5/pcp.conf.5 @@ -0,0 +1,119 @@ +'\"! tbl | mmdoc +'\"macro stdmacro +.\" +.\" Copyright (c) 2000-2004 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PCP.CONF 5 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pcp.conf\f1 \- the Performance Co-Pilot configuration and environment file +.\" literals use .B or \f3 +.\" arguments use .I or \f2 +.SH SYNOPSIS +.I /etc/pcp.conf +.SH DESCRIPTION +When using Performance Co-Pilot (PCP) tools and utilities +and when calling PCP library functions, a standard set of +environment variables are defined in +.IR /etc/pcp.conf . +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 +.IR /etc/pcp.env (5) +shell script and queried by C/C++ programs using the +.IR pmGetConfig (3) +library function. +If a variable is already defined in the environment, +the values in +.I pcp.conf +do +.B not +override those values, i.e. the values in +.I pcp.conf +serve as installation defaults only. +.PP +Both the +.I pcp.env +and +.I pcp.conf +files are expected to be found in +.I /etc +by default. +If required, the +.I pcp.conf +file may be relocated and +.B PCP_CONF +set in the environment to specify the full path to the new location. +The +.I pcp.env +file can not be relocated (this is the only hard coded path +required by PCP). +.PP +The syntax rules for +.I pcp.conf +are as follows : +.IP 1. 4 +the general syntax is +.br +.ce 1 +.B "PCP_VARIABLE_NAME=variable value to end of line" +.IP 2. 4 +lines that begin with +.B # +and all blank lines are ignored. +.IP 3. 4 +all variables must be prefixed with +.BR PCP_ . +This is a security issue - variables that do not have this prefix will +be silently ignored. +.IP 4. 4 +there should be no space between the variable name and the literal +.B = +and no space between the +.B = +and the variable value (unless the value actually starts with a space). +This is required because the +.I pcp.conf +file may be sourced directly by Makefiles as well as interpreted by the +.I pcp.env +script and the +.I "pmGetConfig" +function. +.IP 5. 4 +variable values may contain spaces and should +.B not +be quoted. +The +.I pcp.env +script automatically quotes all variable values from the character +immediately following the +.B = +through to the end of the line. +.PP +For further details and an explanation of the use of +each variable, see the comments in the +.I /etc/pcp.conf +file itself. +.SH ENVIRONMENT +The +.B PCP_CONF +environment variable specifies an alternative path to the +.I pcp.conf +file. +.SH SEE ALSO +.BR PCPIntro (1), +.BR PCPIntro (3), +.BR PMAPI (3), +.BR pmGetConfig (3) +and +.BR pcp.env (5). diff --git a/man/man5/pcp.env.5 b/man/man5/pcp.env.5 new file mode 100644 index 0000000..edd90d4 --- /dev/null +++ b/man/man5/pcp.env.5 @@ -0,0 +1,61 @@ +'\"! tbl | mmdoc +'\"macro stdmacro +.\" +.\" Copyright (c) 2000-2004 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PCP.ENV 5 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pcp.env\f1 \- script to set Performance Co-Pilot run-time environment variables +.\" literals use .B or \f3 +.\" arguments use .I or \f2 +.SH SYNOPSIS +.I /etc/pcp.env +.SH DESCRIPTION +The +.I pcp.env +script is sourced by assorted Performance Co-Pilot (PCP) scripts +and utilities to define the PCP operating environment variables. +The conjugate for executable programs using the PCP libraries is the +.IR __pmGetConfig (3) +function. +.PP +Typical usage of +.I pcp.env +in a script is as follows : +.IP + #! /bin/sh + + # source the PCP environment variables + . /etc/pcp.env + rest of script ... + +.PP +The full syntax and semantics of the +.I pcp.conf +file and the +.I __pmGetConfig +function are described in their respective reference pages. +.SH ENVIRONMENT +The +.B PCP_CONF +environment variable specifies an alternative path to the +.I pcp.conf +file. +.SH SEE ALSO +.BR PCPIntro (1), +.BR PCPIntro (3), +.BR PMAPI (3), +.BR __pmGetConfig (3) +and +.BR pcp.conf (5). diff --git a/man/man5/pmieconf.5 b/man/man5/pmieconf.5 new file mode 100644 index 0000000..5314463 --- /dev/null +++ b/man/man5/pmieconf.5 @@ -0,0 +1,308 @@ +'\"macro stdmacro +.ie \(.g \{\ +.\" ... groff (hack for khelpcenter, man2html, etc.) +.TH PMIECONF 5 "PCP" "Performance Co-Pilot" +\} +.el \{\ +.if \nX=0 .ds x} PMIECONF 5 "PCP" "Performance Co-Pilot" +.if \nX=1 .ds x} PMIECONF 5 "Performance Co-Pilot" +.if \nX=2 .ds x} PMIECONF 5 "" "\&" +.if \nX=3 .ds x} PMIECONF "" "" "\&" +.TH \*(x} +.rr X +\} +.SH NAME +pmieconf \- generalized pmie rules and customizations +.SH DESCRIPTION +The pmieconf file formats are used by the +.BR pmieconf (1) +tool as a way to generalize +.BR pmie (1) +rule sets such that they can be easily configured for different systems and +different environments. +There are two completely different (although closely related) file formats +discussed here, namely ``pmieconf-rules'' and ``pmieconf-pmie''. +.PP +The directory +.B $PCP_VAR_DIR/config/pmieconf +contains information about all the default system +.B pmie +generalized rules and variables, including default values for all variables. +These files are in the pmieconf-rules format. +Although new pmieconf-rules files can be added, the files in this directory +should never be changed. +Instead, use the +.B pmieconf +utility to change variable values in the +.B pmie +configuration file. +.PP +The pmieconf-pmie format allows site specific customizations of the rules +contained in pmieconf-rules files and their associated variables. +The pmieconf-pmie format is generated by +.B pmieconf +and should not be edited by hand. +This generated file is in the +.B pmie +format, with some additional information held at the head of the file \- thus, +the pmieconf-pmie format is a superset of the +.B pmie +file format (extended to hold customizations to the generalized rules, but +also containing the actual performance rules for +.B pmie +to evaluate) which can also be parsed by +.B pmie +(all extensions are hidden within comments, and are thus meaningless to +.B pmie +itself). +.PP +The file +.B $PCP_VAR_DIR/config/pmieconf/config.pmie +contains local system settings for +.B pmieconf +configurable variables. +The variable settings in this file replace the default values specified in +.BR $PCP_VAR_DIR/config/pmieconf/*/* . +.SH PMIECONF-PMIE SYNTAX +All rule customization lines in a valid pmieconf-pmie specification +are prefixed by ``//'' and are located at the head of the file \- +this allows files containing a pmieconf-pmie specification to be +successfully parsed by +.BR pmie . +A pmieconf-pmie must always have the first line in the form: +.sp +.nf + // pmieconf-pmie \f2version\f1 \f2pmieconf_path\f1 +.fi +.sp +The +.I version +specifies which version of the pmieconf-pmie syntax should be used to +parse this file. +Currently the only supported version is 1. The +.I pmieconf_path +specifies the path to the pmieconf-rules files which were used, by +.BR pmieconf , +to generate this file. This is discussed in the +.BR pmieconf (1) +man page (see the +.B \-r +option). +.PP +The remainder of the specification consists of one line entries for each +of the modified variables. The syntax for each line is: +.sp +.nf + // \f2rule_version\f1 \f2rule_name\f1 \f2rule_variable\f1 = \f2value\f1 +.fi +.sp +The +.I rule_version +and +.I rule_name +are used to identify the rule with which to associate the customization. +These are followed by the +.I rule_variable +name (i.e. the variable of rule +.I rule_name +which has been changed) +for which the new +.I value +is to be used. +.PP +A pmieconf-pmie specification must be terminated with the ``end'' keyword. +This is used by +.B pmieconf +to distinguish where the customizations ends, and the actual +.B pmie +rule component begins. +.SH PMIECONF-PMIE EXAMPLE +The following example is a valid pmieconf-pmie format file, as generated by +.BR pmieconf . +In order to make changes by hand which are preserved by +.BR pmieconf , +see the comments contained in the generated file (below) as to where such +changes should be made. +.sp +.nf + // pmieconf-pmie 1 $PCP_VAR_DIR/config/pmieconf + // 1 memory.exhausted delta = "4 minutes" + // 1 memory.exhausted enabled = yes + // 1 memory.exhausted pcplog_action = yes + // end + // + // --- START GENERATED SECTION (do not change this section) --- + // generated by pmieconf on: [DATESTAMP] + // + + // 1 memory.exhausted + delta = 4 minutes; + some_host ( + ( avg_sample (swap.pagesout @0..9 ) ) > 0 && + 30 %_sample swap.pagesout >= 5 + ) -> shell 10 min "$PCP_BINADM_DIR/pmpost Severe demand for real memory" \\ + " %vpgsout/s@%h"; + + // --- END GENERATED SECTION (changes below will be preserved) --- +.fi +.sp +.PP +To see how this all works, you can generate this file as follows: +.sp +.nf + # cat \- | pmieconf \-f /tmp/pmieconf.out \\ + \-r $PCP_VAR_DIR/config/pmieconf/memory:$PCP_VAR_DIR/config/pmieconf/global + modify memory.exhausted delta "4 minutes" + modify memory.exhausted enabled yes + modify memory.exhausted pcplog_action yes + ^D + # +.fi +.sp +Then verify that the generated file is a valid +.B pmie +configuration file using: +.sp +.nf + # pmie \-C /tmp/pmieconf.out +.fi +.sp +This parses the file, and then exits after reporting any syntax errors. +Now replace \-C with \-v (above), and watch +.B pmie +do its work! +.SH PMIECONF-RULES SYNTAX +A pmieconf-rules specification consists of a number of separate data objects +which together form a complete rule specification (note that a specification +may span multiple files and even multiple subdirectories). +Each object must have an +.I identifier +string and a data +.IR type , +followed by an (optional) list of +.IR attribute s. +.PP +The generic specification of a pmieconf-rules object is thus: +.sp +.nf + \f2type\f1 \f2identifier\f1 [ \f2attribute\f1 = \f2value\f1 ]* ; +.fi +.sp +The set of valid +.IR type s +is: "rule" (rule definition), "string" (arbitrary, double-quote enclosed +string), "double", "integer", "unsigned", "percent" (real number between 0 +and 100), "hostlist" (space separated list of host names), "instlist" (space +separated list of metric instance names), and the four +.B pmie +action types, namely +"print", "shell", "alarm", and "syslog". +.PP +Rule names use the ``.'' character to introduce the concept of a rule group, +e.g. "memory.exhausted" associates this rule with the "memory" group. +.B pmieconf +can operate at either the level of rule groups or individual rules. +The group name "global" is reserved and may not be used with any rule. +.PP +Usually when an object is created it is associated with the current rule. +However, if an object's name is preceded by the reserved group name "global", +then that object is visible to all rules. +.PP +The set of valid +.IR attribute s +is: "help" (descriptive text about this object), "modify" (\f2value\f1 is +yes/no, flags whether +.B pmieconf +should allow changes), "enabled" (\f2value\f1 is yes/no, flags whether this is +on or off - only meaningful for rules and actions), "display" (yes/no - flags +whether +.B pmieconf +should show this object), "default" (\f2value\f1 determined by \f2type\f1, and +is the default value for this object), and specific to objects of rule type +are the "version", "predicate", and "enumerate" attributes. "version" and +"predicate" are fairly self explanatory ("predicate" must equate to a valid +.B pmie +rule when expanded), but "enumerate" requires further discussion. +.PP +The "enumerate" clause is useful when you wish to generate multiple, similar +.B pmie +rules from a single predicate. +This is most useful for rule definitions wishing to use the "some_inst" +clause in the +.B pmie +language across multiple hosts. +For a rule to use these together, it must be certain that the +instance list is the same on all of the monitored hosts. +This is rarely true, so the "enumerate" attribute allows us to generate +multiple rules, expanded over variables of either type "instlist" or "hostlist". +These variables make up the value for the "enumerate" attribute \- which is +a space-separated list of "instlist" or "hostlist" variable names. +.PP +Objects can be incorporated into other object definitions using the +$\f2identifier\f1$ syntax. See the example later for more insight into +how this is useful. +.PP +When +.B pmieconf +is generating the +.B pmie +configuration file, it looks at each enabled rule with N enabled +actions (where N > 0) and expands the string: +.sp +.nf + // "version" \f2identifier\f1 + delta = $delta$; + "predicate" -> $threshold$ $action1$ & ... & $actionN$ ; +.fi +.sp +The delta, threshold, and action variables are defined globally +(using the "global" keyword) for all rules, but can, of course, +be changed at the level of an individual rule or rule group. +.SH PMIECONF-RULES EXAMPLE +The following is an example of a single pmieconf-rules specification, +showing a number of different aspects of the language discussed above. +The example defines a rule ("memory.exhausted") and a string ("rule"). +.sp +.nf + rule memory.exhausted + default = "$rule$" + predicate = + "some_host ( + ( avg_sample (swap.pagesout $hosts$ @0..9 ) ) > 0 && + $pct$ %_sample swap.pagesout $hosts$ @0..9 >= $threshold$ + )" + enabled = yes + version = 1 + help = + "The system is swapping modified pages out of main memory to the + swap partitions, and has been doing this on at least pct of the + last 10 evaluations of this rule. + There appears to be insufficient main memory to meet the resident + demands of the current workload."; + + string rule + default = "Severe demand for real memory" + modify = no + display = no; +.fi +.sp +Note that for the above rule to be complete, "threshold" and "pct" would +also need to be defined - for the full expression of this rule, refer to +.IR $PCP_VAR_DIR/config/pmieconf/memory/exhausted . +.PP +.SH FILES +.PD 0 +.TP 10 +.IR $PCP_VAR_DIR/config/pmieconf/ */* +generalized system resource monitoring rules +.TP 10 +.I $PCP_VAR_DIR/config/pmieconf/config.pmie +default super-user settings for system resource monitoring rules +.TP 10 +.I $HOME/.pcp/pmie/config.pmie +default user settings for system resource monitoring rules +.PD +.SH SEE ALSO +.BR pmie (1) +and +.BR pmieconf (1). diff --git a/man/man5/pmns.5 b/man/man5/pmns.5 new file mode 100644 index 0000000..6d6c82c --- /dev/null +++ b/man/man5/pmns.5 @@ -0,0 +1,252 @@ +'\"! tbl | mmdoc +'\"macro stdmacro +.\" +.\" Copyright (c) 2000-2004 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMNS 5 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmns\f1 \- the performance metrics name space +.\" literals use .B or \f3 +.\" arguments use .I or \f2 +.SH SYNOPSIS +.I $PCP_VAR_DIR/pmns +.SH DESCRIPTION +When using the Performance Metrics Programming Interface (PMAPI) +of the Performance Co-Pilot (PCP), +performance metrics are identified by an external name in a +hierarchic Performance Metrics Name Space (PMNS), and an +internal identifier, the Performance Metric Identifier (PMID). +.PP +A PMNS specifies the association between a metric's name and its PMID. +.PP +A PMNS is defined on one or more ASCII source files. +.PP +Loading of a PMNS is done by calling +.BR pmLoadNameSpace (3) +or +.BR pmLoadASCIINameSpace (3). +.PP +By default duplicate PMIDs are not allowed in the PMNS, +although +.BR pmLoadASCIINameSpace (3) +provides an alternative interface with user-defined control +over the processing of duplicate PMIDs in the PMNS. +The external format for a PMNS conforms to the syntax +and semantics described in the following sections. +.PP +There is one default PMNS in the files below +.IR $PCP_VAR_DIR/pmns , +although users and application developers are free to +create and use alternate PMNS's. +For an example of this, see +the PCP Tutorial in +.IR $PCP_DEMOS_DIR/Tutorial . +.PP +Although an application can call +.BR pmLoadNameSpace (3), +normally this is only done directly for the +.B \-n +command line option where an explicit root PMNS file is specified. +Since PCP version 2 uses a distributed PMNS (see below), +an application can extract PMNS information from a +host's PMCD or an archive. If the PMNS source +is a version 1 archive (see +.BR PCPIntro (1)), +however, +then the local PMNS will be loaded using the path specified by the +environment variable +.BR PMNS_DEFAULT . +.SH DISTRIBUTED PMNS +In PCP version 1, the PMNS functions in the API all operated on +a PMNS loaded locally from a file. Since PCP version 2, however, +PMNS functions may get the PMNS information remotely from a PMCD +or directly from the meta data of an archive. +.SH PROCESSING FRAMEWORK +.de CW +.ie t \f(CW\\$1\f1\\$2 +.el \fI\\$1\f1\\$2 +.. +The PMNS specification is initially passed through +.BR pmcpp (1). +This means the following facilities may be used in the specification +.IP + 3n +C-style comments +.IP + 3n +.CW #include +directives +.IP + 3n +.CW #define +directives and macro substitution +.IP + 3n +conditional processing via +.CW #ifdef +\&... +.CW #endif , +etc. +.PP +When +.BR pmcpp (1) +is executed, the ``standard'' include directories are the current directory and +.IR $PCP_VAR_DIR/pmns . +.SH SYNTAX +The general syntax for a non-leaf node in the PMNS is as follows +.PP +.ft CW +.nf +pathname { + name [pmid] + ... +} +.fi +.ft R +.PP +Where +.CW pathname +is the full pathname from the root of the PMNS to this non-leaf node, +with each +component in the pathname separated by a ``.''. +The root node for the PMNS must have the special +name ``root'', but the common prefix ``root.'' must be omitted from +all pathnames. +Each component in the pathname must begin with an alphabetic character, +and be followed by zero or +more characters drawn from the alphabetics, the digits and the underscore +``_'') character. +For alphabetic characters in a pathname component, upper and lower case are distinguished. +.PP +Non-leaf nodes in the PMNS may be defined in any order. +.PP +The descendent nodes are defined by the set of +.CW names , +relative to the +.CW pathname +of their parent non-leaf node. For the descendent nodes, leaf +nodes have a +.CW pmid +specification, non-leaf nodes do not. The syntax for +the +.CW pmid +specification has been chosen to help manage the allocation of +PMIDs across disjoint and autonomous domains +of administration and implementation. Each +.CW pmid +consists of 3 integer +parts, separated by colons, e.g. 14:27:11. This hierarchic numbering +scheme is intended to mirror the implementation hierarchy of +performance metric domain, metrics cluster (data structure or +operational similarity) and individual metric. In practice, the +two leading components are likely to be macros in the PMNS specification +source, and +.BR pmcpp (1) +will convert the macros to integers. These macros for +the initial components of the +.CW pmid +are likely to be defined either in +a standard include file, e.g. \c +.IR $PCP_VAR_DIR/pmns/stdpmid , +or in the current source file. +.PP +To support dynamic metrics, where the existence of a metric is known to +a PMDA, but not visible in the PMNS, a variant syntax for the +.CW pmid +is supported, namely a domain number followed by asterisks for the other +components of the +.CW pmid , +e.g. 14:*:*. +The corresponding metric name forms the root of a subtree of dynamic +metric names defined in the corresponding PMDA as identified by the domain +number. +.PP +The current allocation of the high-order (PMD or domain) component +of PMIDs is as follows. +.TS +box,center; +c | c +n | l. +Range Allocation +_ +0 reserved +_ +1-31 PMDAs from the PCP base product +_ +32-39 Oracle +_ +40-47 Sybase +_ +48-55 Informix +_ +56-58 SNMP Gateway PMDA +_ +59-63 Linux PMDAs +_ +64-69 ISV PMDAs +_ +70-128 more PMDAs from the PCP base product +_ +129-510 End-user PMDAs and demo PMDAs +_ +511 RESERVED +.TE +.SH EXAMPLE +.ft CW +.nf +#define KERNEL 1 +#define FOO 317 +root { + network + cpu + dynamic FOO:*:* +} + +#define NETWORK 26 +network { + intrate KERNEL:NETWORK:1 + packetrate +} + +network.packetrate { + in KERNEL:NETWORK:35 + out KERNEL:NETWORK:36 +} + +#define CPU 10 +cpu { + syscallrate KERNEL:CPU:10 + util +} + +#define USER 20 +#define SYSTEM 21 +#define IDLE 22 + +cpu.util { + user KERNEL:CPU:USER + sys KERNEL:CPU:SYSTEM + idle KERNEL:CPU:IDLE +} +.fi +.ft R +.SH SEE ALSO +.BR PCPIntro (1), +.BR pmcd (1), +.BR pmcpp (1), +.BR PCPIntro (3), +.BR PMAPI (3), +.BR pmErrStr (3), +.BR pmGetConfig (3), +.BR pmLoadASCIINameSpace (3), +.BR pmLoadNameSpace (3), +.BR pcp.conf (5) +and +.BR pcp.env (5). diff --git a/man/man5/pmview.5 b/man/man5/pmview.5 new file mode 100644 index 0000000..f60bfec --- /dev/null +++ b/man/man5/pmview.5 @@ -0,0 +1,1036 @@ +.TH PMVIEW 5 "" "Performance Co-Pilot" +.SH NAME +\f3pmview\f1 \- configuration file format for performance +.SH DESCRIPTION +This man page describes version 2.1 of the +.B pmview +configuration file format. +.PP +The configuration format supports metrics from multiple hosts or archives. A +configuration file can specify metrics without a source, with different hosts +and different archives. However, a configuration file that contains archives +may only have one archive for anyone host. When in ``replay'' mode, any +metrics with host specific sources require an archive to be specified for that +host on the command line or as a source to a previous metric. The archive must +be the same archive (based on a string comparison of the archive names) of any +archives specified in the configuration file for the same host. +.PP +The time controls will list all hosts that are specified on the command line +and the configuration file in the timezone listing (see +.BR pmtime (1)). +.PP +The configuration file format is based on a two-dimensional grid which +can contain a variety of bars, stacks, links, pipes, labels and other +grids. The grids resize each column and row to match the size of the +largest item in that column or row. A configuration file that +contains only one object does not require a grid. The +.B pmview +configuration file starts with an identification header in the first +non-comment line: +.PP +.in 1.0i +.ft CW +.nf +pmview Version 2.1 \f2[command_line]\f1 +.fi +.ft R +.in +.PP +The optional +.I command_line +should be the command line with which the tool was launched, if the +configuration file has been generated by another tool. This is useful for +applications that are to be restarted automatically on the next login, after +the user has logged out while +.B pmview +was still running. +Care should be taken to ensure that the command specified is either a +full pathname or will be found on the PATH available at login. +.PP +All lines which begin with ``#'' are treated as comments and +ignored. Otherwise, all spaces, tabs and newlines are treated as white space +so multiple commands may be on the same line. +.PP +The syntax for specifying values in the configuration file is consistent for +all commands, namely: +.TP 4n +.I color +A color must be either a +.BR X (1) +color name, a +.BR X (1) +numerical color, or three normalized +.I real +values representing the saturation of red, green and blue. For example, +the following colors are identical: +.PP +.in 1.5i +.ft CW +.nf +red +rgbi:1.0/0.0/0.0 +1.0 0.0 0.0 +.fi +.ft R +.in +.TP 4n +.I int +An integer. +.TP 4n +.I metric +A metric consists of an optional source (host or archive), the metric name, +an optional instance list immediately after name, followed by the maximum (or +normalization value). A colon (``:'') is used to separate a host name from the +metric, and a forward slash (``/'') to separate an archive name from the +metric. Instances are enclosed in square brackets and comma separated. Each +instance may be enclosed in quotes. +.IP +For example, some legal metrics are: + +.in 1.5i +.ft CW +.nf +kernel.all.cpu.idle 4000 +myhost:kernel.all.cpu.idle[cpu0,"cpu3"] 1000.0 +/path/to/myarchive/kernel.all.cpu.idle[cpu1] 1000 +.fi +.ft R +.in + +To assist the process of matching instance names, two further comparisons are +made beyond a simple string comparison. If the instance name contains +spaces, only the first word in the instance name is required to match the +instance, assuming that the first word is unique. If the first word is not +unique, only the first matching instance will be selected. The second +comparison occurs if the first word is a number with leading zeros. Any +leading zeros will be skipped before comparing the first word again. This +permits process ids used in the +.I proc +metrics to be easily matched, without specifying the entire instance name. For +example, to visualize the user and system time of +.I init +use the metric specification + +.in 1.5i +.ft CW +.nf +proc.psusage.utime[1] 1000 +proc.psusage.stime[1] 1000 +.fi +.ft R +.in +.TP 4n +.I name +A name for an object which may be referred to later in the configuration file. +Names must be a single word consisting of all alphanumeric characters, as well +as underscores, dashes and colons. It is recommended that names do not begin +with an underscore as this may be interpreted as a keyword. +.TP 4n +.I pos +This is the position of the object within the grid. The syntax of a position +is: +.IP +.in 1.0i +[ [\f2x\f1 \f2z\f1] [ [\f2width\f1 \f2depth\f1] [\f2alignment\f1] ] ] +.in +.TP 14 +.I " x" +The horizontal coordinate (left to right) of the object, starting at 0. The +default +.I x +is 0. +.TP +.I " z" +The vertical coordinate (top to bottom) of the object, starting at 0. The +default +.I z +is 0. +.TP +.I " width" +The number of columns occupied by the object. The default +.I width +is 1. +.TP +.I " depth" +The number of rows occupied by the object. The default +.I depth +is 1. +.TP +.I " alignment" +The edge or corner that the object is aligned with. Possible alignments +include: \f2north\f1, \f2south\f1, \f2east\f1, \f2west\f1, \f2northeast\f1, +\f2northwest\f1, \f2southeast\f1, \f2southwest\f1 and \f2center\f1. +Abbreviations like \f2se\f1 and \f2SE\f1 are also accepted. The default +alignment is \f2center\f1. +.IP +The size of an object may not be known as the number of instances for some +metrics will vary between hosts and +PMDA +configurations. Therefore, the position of the object can be used to specify +the likely size of the object, so that the position of the surrounding objects +is appropriately adjusted. +.IP +The following are legal positions: +.TP 21 +.ft CW + 0 5 +.ft R +The object is centered at grid position 0,5 occupying 1 grid square. +.TP +.ft CW + 1 2 north +.ft R +The object is aligned with the north edge of position 1,2 occupying 1 grid +square. +.TP +.ft CW + 2 2 2 1 east +.ft R +The object is aligned to the eastern edge of position 3,2 and occupies 2 grid +squares (2,2 and 3,2). +.TP 4n +.I string +A string is a series of characters enclosed in double quotes. A string may +not contain newlines or escaped double quotes. + +.PP +There are several parameters that may affect the size, shape and color of +objects when they are displayed. These parameters are scoped so that they only +alter objects defined later in the same scope. Therefore, parameter settings +at the top of a configuration file affect the entire scene, unless they are +changed later in the file. Most of these parameters are also resources. +.TP 4n +\f3_barLength\f1 \f2int\f1 +The side length of the +.B _bar +and +.B _stack +blocks. Default is 28. +.TP 4n +\f3_barHeight\f1 \f2int\f1 +The maximum height of a +.B _bar +and +.B _stack +blocks. Default is 80. +.TP 4n +\f3_baseColor\f1 \f2color\f1 +The color of +.BR _bar , +.B _grid +and +.B _stack +base planes. Default is rgbi:0.15/0.15/0.15. +.TP 4n +\f3_baseHeight\f1 \f2int\f1 +The height of +.BR _bar , +.B _grid +and +.B _stack +base planes. Default is 2. +.TP 4n +\f3_gapWidth\f1 \f2int\f1 +The gap between blocks in a +.B _bar +object in the X-axis. The default is 8. +.TP 4n +\f3_gapDepth\f1 \f2int\f1 +The gap between blocks in a +.B _bar +object in the Z-axis. The default is 8. +.TP 4n +\f3_gapLabel\f1 \f2int\f1 +The gap between the base of a +.B _bar +object, and any metric or instance labels. The default is 6. +.TP 4n +\f3_gridWidth\f1 \f2int\f1 +The minimum width of a +.B _grid +column. The default is 20. +.TP 4n +\f3_gridDepth\f1 \f2int\f1 +The minimum depth of a +.B _grid +row. The default is 20. +.TP 4n +\f3_labelMargin\f1 \f2int\f1 +The margin around a +.B _label +object. The default is 5. +.TP 4n +\f3_labelColor\f1 \f2color\f1 +The color of +.B _label +and +.B _bar +labels. The default is white. +.TP 4n +\f3_marginWidth\f1 \f2int\f1 +The extra width of a +.BR _bar , +.B _grid +and +.B _stack +base plane beyond the objects on the plane. The default is 8. +.TP 4n +\f3_marginDepth\f1 \f2int\f1 +The extra depth of a +.BR _bar , +.B _grid +and +.B _stack +base plane beyond the objects on the plane. The default is 8. +.TP 4n +\f3_pipeLength\f1 \f2int\f1 +Total length of a +.BR _pipe. +The default is the value of +.BR _barHeight. +.TP 4n +\f3_scale\f1 \f2real\f1 +The scale applied to the entire scene. This parameter may not be used within +any objects, only at the top of the configuration file. The default is 1.0. +.PP +To simplify the specification of colors, a +.B _colorList +and a +.B _colorScale +may be used to define colors for an object which has metrics +associated with it, i.e. +.BR _bar , +.B _stack +or +.BR _pipe . +A color list may be defined within an object, or named and defined at +the top of a configuration file. A named color list may then be referenced +within multiple objects: +.TP 4n +\f3_colorList\f1 \f2name\f1 \f3(\f1 \f2color\f1 [\f2color\f1...] \f3)\f1 +Associate the +.IR color s +with the color list +.IR name . +The assignment of colors to blocks depends on the type of an +object. For example, the color list called +.I foo +has the same color three times: + +.RS 4 +.ft CW +.nf +_colorList foo ( red rgbi:1.0/0.0/0.0 1.0 0.0 0.0 ) +.fi +.ft R +.RE + +.TP 4n +\f3_colorScale\f1 \f2name\f1 \f2color\f1 \f3(\f1 \f2color\f1 \f2real\f1 [\f2color\f1 \f2real\f1...] \f3)\f1 +Associate the +.IR color s +and +.IR real s +with the color list +.IR name . +The initial +.I color +is the default color of the object. The object will change color to the other +colors when the normalized value of the object is equal to or greater than +each +.IR real . +Therefore, each +.I real +must be larger than the previous +.IR real , +and should be in the range 0.0 to 1.0. This scale gradually changes from blue +to red: +.PP +.RS 4 +.ft CW +.nf +_colorScale coldToHot blue ( rgbi:0.5/0.0/1.0 0.3 + purple 0.6 + rgbi:1.0/0.0/0.5 0.8 + red 0.95) +.fi +.ft R +.RE +.PP +There are several different object types which could be found in a +.B pmview +scene: +.BR _bar , +.BR _stack , +.BR _pipe , +.BR _grid , +.BR _link , +and +.BR _label . +There is also +.B _xing +which is a special type of the +.BR _link . +The +.BR _bar , +.B _stack +and +.B _pipe +objects are modulated by metric values, a +.B _label +is fixed text, +.B _link +and +.B _xing +are interconnects and a +.B _grid +is a container of objects, including other +.B _grid +objects, which controls the layout of the scene. A +.B _grid +object is only required if there are two or more objects in the scene. +.PP +.BR _bar , +.B _grid +and +.B _stack +objects may have base planes which provide a point of reference for the blocks +as they change height. A label can be applied to the base plane +.B _grid +object if it is +.B _shown +with: + +.in 1.5i +.ft CW +.nf +\f3_baseLabel\f1 \f2name\f1|\f2string\f1 +.fi +.ft R +.in + +.B _baseLabel +should be used within the scope of the relevant +.BR _bar , +.B _grid +or +.B _stack +object. The first ``\\n'' characters in the string will be replaced by a new +line. Subsequent ``\\n'' characters will be ignored. +.PP +For a scene to be valid it must contain at least one modulated object. +.PP +The objects are defined as: +.TP 4n +\f3_bar\f1 [\f2options\f1] \f3(\f1 [\f2metric-list\f1] [\f2color-list\f1] [\f2label-list\f1] \f3)\f1 +A +.B _bar +object represents a collection of blocks. The number of blocks depends on the +number of metrics and metric instances assigned to the object. By default, the +blocks are modulated by changing the height of each block. Alternatively, +blocks may be modulated by changing color, or both height and color. Each +color in the +.I color-list +is assigned to each metric. Therefore, multiple instances of the one metric +will have the same color. The +.I options +that may be passed to a +.B _bar +object are: +.RS 4n +.TP 4n +.I pos +The position of the +.B _bar +object within the current +.B _grid +object. +.TP 4n +\f3_col\f1|\f3_row\f1 +Position the blocks so that each instance is in a column +.RB ( _col ) +or a row +.RB ( _row ). +This implies that each different metric is in a separate row or column, +respectively. The default is +.BR _col . +.TP 4n +\f3_show\f1|\f3_hide\f1 +Is the base plane visible? Default is +.BR _show . +.TP 4n +\f3_ymod\f1|\f3_colormod\f1|\f3_colorymod\f1 +Modulate the blocks by adjusting their height +.RB ( _ymod ), +color +.RB ( _colormod ) +or both height and color +.RB ( _colorymod ). +.TP 4n +\f3_cube\f1|\f3_cylinder\f1 +Set the shape of the blocks. The default is +.BR _cube . +.RE +.RS 4n +.TP 4n +\f3_groupbymetric\f1|\f3_groupbyinst\f1|\f3_groupbyrow|\f1|\f3groupbycol\f1 +Set the grouping of blocks when launching other tools. For tools like +.BR pmchart (1) +some views may generate many small charts which cannot be drawn entirely within +the screen. Another problem is it may be more appropriate to generate charts +with the same instance in each chart, rather then the same metric. The group +specifiers control the algorithm used so that a separate chart will be drawn +for each +.B _metrics +specification +.RB ( _groupbymetric ), +for the first, second etc. instance of each +.B _metric +.RB ( _groupbyinst ), +or by the rows and columns of the +.B _bar +object depending on +.B _row +or +.BR _col . +The default is +.BR _groupbymetric . +.PP +The options must be specified in this order, although preceding options are +not required. Therefore, this is legal: + +.in 1.5i +.ft CW +.nf +_bar _hide _cylinder ( ... ) +.fi +.ft R +.in + +The metrics, colors and labels are specified within the brackets in any order. +Only the +.I metric-list +is mandatory. +.TP 4n +.I metric-list +A +.B _bar +metric list contains a list of metric names, normalization values and an +optional label for the metric: + +.RS 4n +.ft CW +.nf +\f3_metrics\f1 \f3(\f1 \f2metric\f1 \f2real\f1 [\f2string\f1] [\f2metric\f1 \f2real\f1 [\f2string\f1]...] \f3)\f1 +.fi +.ft R +.RE + +.TP 4n +.I color-list +A +.B _bar +color list may be a named color list that was defined earlier, or an unnamed +color list. A +.B _colorScale +list should be used when using +.B _colormod +or +.B _colorymod +modulation. Therefore, the syntax for color lists within a +.B _bar +object are any of: + +.RS 4n +.ft CW +.nf +\f3_colorList\f1 \f2name\f1 +\f3_colorList\f1 \f3(\f1 \f2color\f1 [\f2color\f1...] \f3)\f1 +\f3_colorScale\f1 \f2name\f1 +\f3_colorScale \f2color\f1 \f3(\f1 \f2color\f1 \f2real\f1 [\f2color\f1 \f2real\f1...] \f3)\f1 +.fi +.ft R +.RE +.TP 4n +.I label-list +In addition to labels for each metric in the +.IR metric-list , +metric and instance labels may be defined using +.B _metriclabels +and +.B _instlabels +statements. The position of the labels around the +.B _bar +object depends on the +.B _row +or +.B _col +orientation of metrics and instances, and whether the label is read +.B _towards +the +.B _bar +object, or +.BR _away . +The default is +.BR _towards . + +.RS 4 +.ft CW +.nf +\f3_metriclabels\f1 [\f3_away\f1|\f3_towards\f1] \f3(\f1 \f2name\f1|\f2string\f1 [\f2name\f1|\f2string\f1...] \f3)\f1 +\f3_instlabels\f1 [\f3_away\f1|\f3_towards\f1] \f3(\f1 \f2name\f1|\f2string\f1 +[\f2name\f1|\f2string\f1...] \f3)\f1 +.fi +.ft R +.RE + +.RE +.TP 4n +\f3_grid\f1 [\f2pos\f1] [\f3_show\f1|\f3_hide\f1] \f3(\f1 \f2objects\f1 \f3)\f1 +A +.B _grid +object is a container for objects, including other +.B _grid +objects. +The rows and columns of a +.B _grid +object are resized to the largest object in the row or column. If an object +spans multiple rows and/or columns, those rows and columns may be partly +resized to contain the object. However, the resizing of rows and columns for +objects occupying multiple rows and columns occurs after resizing for objects +occupying only one grid square. + +A collision between objects occupying the same squares will be reported as an +error message and the later object will be ignored. + +The options to a +.B _grid +object control the position +.RI ( pos ) +of the +.B _grid +object in the parent +.BR _grid , +and indicate whether to +.B _show +or +.B _hide +the +.B _grid +base plane. By default, the base plane is hidden. + +The parameters described above may be specified within the brackets of a +.B _grid +object, however they only apply to the objects within the +.BR _grid , +not the +.B _grid +itself. For a parameter to be applied to a +.B _grid +object, it must be specified before the +.B _grid +object declaration. + +.RE +.TP 4n +.I "\f3_label\f1 [\f2options\f1] \f2string\f1" +A +.B _label +object draws the contexts of +.I string +at the location, orientation and size specified in the +.IR options : +.RS 4n +.TP 4n +.I pos +The position of the +.B _label +object +in the current +.B _grid +object. +.TP 4n +\f3_left\f1|\f3_right\f1|\f3_up\f1|\f3_down\f1 +The orientation of the +.IR string . +The direction indicates the direction the label is read. Therefore, +.B _right +is the default since the string is read from left to right. +.TP 4n +\f3_small\f1|\f3_medium\f1|\f3_large\f1 +The font size. The default is +.BR _medium . +.RE + +.RE +.TP 4n +\f3_link\f1 \f2pos\f1 [\f2string\f1] +A +.B _link +object draws a straight or L-shaped horizontal round ``pipe'' with +diameter equal to 80% of the +.I _baseHeight +of an enclosing +.BR _grid . +The properties of the object are defined by the options: + +.RS 4n +.TP 4n +.I pos +sets both the position of the +.B _link +on the grid and its shape. +.B _link +starts in the column and row on the +.B _grid +specified by first two numbers in the +.I pos +and spans the number of columns and rows set by the second two +numbers. The +.I alignment +value is used to decide the orientation of the link (links are always +aligned at the center): +.I east +and +.I west +links are straight and going from left to right, +.I north +and +.I south +links are straight and going from far end of the grid to near end, +.I northeast, +.I northwest, +.I southeast +and +.I southwest +links are L-shaped and connect the corresponding points of the compass, +i.e. a +.I northeast +link takes on the general shape of the Latin letter ``L''. +.TP 4n +.I string +sets the ``tag'' for the +.B _link +which will be displayed in the text window when the pointer is over the +link. +.RE + + +.RE +.TP 4n +\f3_pipe\f1 \f2pos\f1 \f3(\f1 [\f2metric-list\f1] [\f2color-list\f1] [\f2tag\f1] \f3)\f1 +A +.B _pipe +object represent a set of cylinders, placed on top of each other and +oriented parallel to the base plane. The diameter of a +.B _pipe +is equal to 80% of +.IR _baseHeight . +The number of blocks is dependent on the number of +metric instances in the +.IR metric-list . +The colors in the +.I color-list +are assigned in turn to each cylinder in the +.BR _pipe . +The length of the +.B _pipe +is defined by the +.IR _pipeLength . + +.RS 4n +.TP 4n +.I pos +defines the position of the +.B _pipe +on the enclosing +.B _grid +and its orientation with +.I alignment +field used to define at which end of the pipe to stack the colored +cylinders. The cylinders are stacked at the corresponding point of the +compass and the pipe's direction is from the point of the compass +towards the center of the compass. Only +.IR east , +.IR west , +.IR north , +and +.I south +are valid values for the pipe's alignment. + +.RE +The metrics, colors and label may be specified within the brackets in any +order. Only the +.I metric-list +is mandatory. +.TP 4n +.I metric-list +A +.B _pipe +metric list contains a list of metric names and normalization values: + +.RS 4n +.ft CW +.nf +\f3_metrics\f1 \f3(\f1 \f2metric\f1 \f2real\f1 [\f2metric\f1 \f2real\f1...] \f3)\f1 +.fi +.ft R +.RE + +.TP 4n +.I color-list +A +.B _pipe +color list may be named color list that was defined earlier, or an unnamed +color list: + +.RS 4n +.ft CW +.nf +\f3_colorList\f1 \f2name\f1 +\f3_colorList\f1 \f3(\f1 \f2color\f1 [\f2color\f1...] \f3)\f1 +.fi +.ft R +.RE + +.TP 4n +.I tag +A +.B _pipe +may have a ``tag'' for the filler block (unanimated block on the +``other'' end of the pipe) which will be displayed in the text window +when the pointer is over that end of the pipe. + +.RS 4n +.ft CW +.nf +\f3_pipeTag\f1 \f2name\f1|\f2string\f1 +.fi +.ft R +.RE + +.RE +.TP 4n +\f3_stack\f1 [\f2options\f1] \f3(\f1 [\f2metric-list\f1] [\f2color-list\f1] [\f2label\f1] \f3)\f1 +A +.B _stack +object represents a set of blocks placed vertically on top of each other. The +number of blocks is dependent on the number of metric instances in the +.IR metric-list . +The colors in the +.I color-list +are assigned to each block in the +.BR _stack . +By default, the height of the +.B _stack +will be the sum of the height of each block. The +.I options +that may be passed to a +.B _stack +object are: +.RS 4n +.TP 4n +.I pos +The position of the +.B _stack +object within the current +.B _grid +object. +.TP 4n +\f3_show\f1|\f3_hide\f1 +Is the base plane visible? Default is +.BR _show . +.TP 4n +\f3_utilmod\f1|\f3_fillmod\f1 +Force the height of the stack to always be the maximum height. This is achieved +by normalizing the height of each block +.RB ( _utilmod ), +or by adding a grey block to the top of the stack +.RB ( _fillmod ). +.TP 4n +\f3_cube\f1|\f3_cylinder\f1 +Set the shape of the blocks. The default is +.BR _cube . +.RE +.RS 4n +.PP +The options must be specified in this order, although preceding options are +not required. Therefore, this is legal: + +.in 1.5i +.ft CW +.nf +_stack 1 1 _north _utilmod ( ... ) +.fi +.ft R +.in + +The metrics, colors and label may be specified within the brackets in any +order. Only the +.I metric-list +is mandatory. +.TP 4n +.I metric-list +A +.B _stack +metric list contains a list of metric names and normalization values: + +.RS 4n +.ft CW +.nf +\f3_metrics\f1 \f3(\f1 \f2metric\f1 \f2real\f1 [\f2metric\f1 \f2real\f1...] \f3)\f1 +.fi +.ft R +.RE + +.TP 4n +.I color-list +A +.B _stack +color list may be named color list that was defined earlier, or an unnamed +color list: + +.RS 4n +.ft CW +.nf +\f3_colorList\f1 \f2name\f1 +\f3_colorList\f1 \f3(\f1 \f2color\f1 [\f2color\f1...] \f3)\f1 +.fi +.ft R +.RE + +.TP 4n +.I label +A +.B _fillmod +type +.B _stack +may have a label for the filler block: + +.RS 4n +.ft CW +.nf +\f3_stackLabel\f1 \f2name\f1|\f2string\f1 +.fi +.ft R +.RE + +.RE +.TP 4n +\f3_xing\f1 \f2col\f1 \f2row\f1 \f2columns\f1 \f2rows\f1 \f2dir1\f1 ... \f2dir4\f1 +A +.B _xing +is a special kind of link which is used to draw a pair of links which +cross each other. To convey the visual impression that the links do +not join, one of the links is drawn as a ``broken'' cylinder. +.I col +and +.I row +define the position on the enclosing grid. +.I columns +and +.I rows +define the size of the bounding box. The end points of the crossing +cylinders are placed exactly in the center of the corner cells of the +bounding box and four small cylinders or stubs are used to join the +perimeter of the bounding box with the end points on the crossing +cylinders. Four +.I dir +values define the orientation of the stubs, starting at the upper left +corner of the +.B _xing +and proceeding clockwise, such that respective stubs are used to join +the point of the compass with the center on the cell (see example). +.RE +.SH EXAMPLE +This simple example illustrates the use of parameters and different object +types: + +.in 1i +.ft CW +.nf +pmview Version 2.1 +# Use a lighter grey for the base planes +_baseColor rgbi:0.5/0.5/0.5 + +# Define colors for CPU object +_colorList cpu ( blue2 red2 yellow2 cyan2 green2 ) + +# The top grid object, but hide it from view +_grid _hide ( + +# Show the current load in a bar object + _bar 0 0 ( + _baseLabel "Load averages over a\\n1, 5 and 15 minute interval" + _metrics ( + kernel.all.load[1] 1 "1" + kernel.all.load[5] 1 "5" + kernel.all.load[15] 1 "15" + ) + _colorList ( blue blue blue ) + ) + +# Add a label below the load bars + _label 0 1 "Load" + +# Change the color of the base plane for later objects + _baseColor pink + +# Show the CPU usage over all CPUs in a utilization stack + _stack 2 0 _south _utilmod ( + _baseLabel "CPU Utilization over all CPUs" + _metrics ( + kernel.all.cpu.user 1000 + kernel.all.cpu.sys 1000 + kernel.all.cpu.intr 1000 + kernel.all.cpu.wait.total 1000 + kernel.all.cpu.idle 1000 + ) + _colorList cpu + ) + +# Add a label below the CPU stack + _label 2 1 "CPU" + +# Create a separate grid for links and pipes + _marginWidth 1 + _marginDepth 1 + _gridSpace 12 + _grid 0 3 5 4 _hide ( + _pipeLength 12 + _baseHeight 12 + + # Add a pipe and a link with western orientation + _pipe 0 0 west ( + _pipeTag "West pipe" + _metrics ( + kernel.all.cpu.user 1000 + kernel.all.cpu.sys 1000 + kernel.all.cpu.idle 1000 + ) + _colorList cpu + ) + + _link 0 2 west "West link" + + # Add xing + _xing 1 0 3 3 west east east west + + # Add a link and a pipe with eastern orientation + _pipe 4 0 east ( + _pipeTag "East Pipe" + _metrics ( + kernel.all.cpu.user 1000 + kernel.all.cpu.sys 1000 + kernel.all.cpu.idle 1000 + ) + _colorList cpu + ) + _link 4 2 east "East link" + ) +) +.fi +.ft R +.in +.SH SEE ALSO +.BR pmview (1). diff --git a/man/retired/pmdahotproc.1 b/man/retired/pmdahotproc.1 new file mode 100644 index 0000000..1311529 --- /dev/null +++ b/man/retired/pmdahotproc.1 @@ -0,0 +1,315 @@ +'\"macro stdmacro +.TH PMDAHOTPROC 1 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmdahotproc\f1 \- Hot Proc performance metrics domain agent (PMDA) +.SH SYNOPSIS +\f3$PCP_PMDAS_DIR/hotproc/pmdahotproc\f1 +[\f3\-C\f1] +[\f3\-d\f1 \f2domain\f1] +[\f3\-l\f1 \f2logfile\f1] +[\f3\-s\f1] +[\f3\-t\f1 \f2interval\f1] +[\f3\-U\f1 \f2username\f1] +\f2configfile\f1 +.br +.SH DESCRIPTION +.B pmdahotproc +is a Performance Metrics Domain Agent (PMDA) which exports +.B proc +performance metrics from an instance domain of processes restricted +to an "interesting" or "hot" set. Unlike the +.B proc +PMDA which has an instance domain equal to the current processes, +.B pmdahotproc +has an instance domain which is a subset of this and is +determined by a configuration file and a refresh interval. +.P +As well as +the +.B proc +metrics, +.B pmdahotproc +provides a \f3cpuburn\f1 metric which specifies the cpu utilization +of the process over the refresh interval, \f3total\f1 metrics which +indicate how much of the cpu that the "interesting" processes are +accounting for, \f3predicate\f1 metrics which show the values of +the reserved variables (see below) that +are being used in the hotproc predicate and \f3control\f1 metrics +for controlling the agent. +.PP +A brief description of the +.B pmdahotproc +command line options follows: +.TP 5 +.B \-C +Parse +.IR configfile , +report any errors and exit. +.TP 5 +.B \-d +It is absolutely crucial that the performance metrics +.I domain +number specified here is unique and consistent. +That is, +.I domain +should be different for every PMDA on the one host, and the same +.I domain +number should be used for the same PMDA on all hosts. +.TP 5 +.B \-l +Location of the log file. By default, a log file named +.I hotproc.log +is written in the current directory of +.BR pmcd (1) +when +.B pmdahotproc +is started, i.e. +.BR $PCP_LOG_DIR/pmcd . +If the log file cannot +be created or is not writable, output is written to the standard error instead. +.TP 5 +.B \-s +With this option, attempts to change the agent configuration by +modifying the values of +\f3hotproc.control.refresh\f1 and \f3hotproc.control.config\f1 using +.BR pmstore(1) +will not be permitted. +Without this option, storing into these \f3hotproc.control\f1 metrics will +be permitted. +.TP 5 +.B \-t +.B pmdahotproc +will regenerate its interesting set of processes using the configuration +predicate, once every +.I interval +period. +The period is specified as a time interval using the syntax +described in +.BR PCPIntro (1). +The default +.I interval +is 60 seconds. +.TP 5 +.B \-U +User account under which to run the agent. +The default is the unprivileged "pcp" account in current versions of PCP, +but in older versions the superuser account ("root") was used by default. +.SH CONFIGURATION +The configuration file consists of one predicate used to determine if +a process should be in the interesting set or not. +.PP +Example configurations files may be found at +.B $PCP_PMDAS_DIR/hotproc/sample.conf +and +.B $PCP_PMDAS_DIR/hotproc/general.conf . +.PP +The predicate is described +using the language specified below. The symbols are based on those +used by +.BR c (1) +and +.BR awk (1) . +.TP +Boolean Connectives +.B && +(and), +.B || +(or), +.B ! +(not), +.B () +(precedence overriding) +.TP +Number comparators +.B < +, +.B <= +, +.B > +, +.B >= +, +.B == +, +.B != +.TP +String comparators +.B == +, +.B != +.TP +String/Pattern comparators +.B ~ +(string matches pattern) +, +.B !~ +(string does not match pattern) +.TP +Reserved variables +.B uid +(user id; type integer) +.B uname +(user name; type string), +.B gid +(group id; type integer) +.B gname +(group name; type string), +.B fname +(process file name; type string), +.B psargs +(process file name with args; type string), +.B cpuburn +(cpu utilization; type float), +.B iodemand +(I/O demand - Kbytes read/written per second; type float), +.B ctxswitch +(number of context switches per second; type float), +.B syscalls +(number of system calls per second; type float), +.B virtualsize +(virtual size in Kbytes; type float), +.B residentsize +(resident size in Kbytes; type float), +.B iowait +(blocked and raw io wait in secs/sec; type float), +.B schedwait +(time waiting in run queue in secs/sec; type float). +.TP +Literal values +.B 1234 +(positive integer), +.B 0.35 +(positive float), +\f3"foobar"\f1 +(string; delimited by \f3"\f1), +.B /[fF](o)+bar/ +(pattern; delimited by \f3/\f1), +.B true +(boolean), +.B false +(boolean) +.TP +Comments +.B #this is a comment +(from \f3#\f1 to the end of the line). +.TP +Examples + cpuburn > 0.2 # cpu utilization of more than 20% + cpuburn > 0.2 && uname == "root" + cpuburn > 0.2 && (uname == "root" || uname == "hot") + psargs ~ /pmda/ && cpuburn > 0.4 + +.PP +The \f3hotproc.predicate\f1 metrics may be used +to see what the values of the reserved variables are +that were used by the predicate at the last refresh. +They do not cover the reserved variables which are +already exported elsewhere. A \f3hotproc.predicate\f1 metric +may not have a value if it is not referenced in the configuration +predicate. + + +.SH INSTALLATION +If you want access to the names, help text and values for the Hotproc +performance metrics, do the following as root: +.PP +.ft CW +.nf +.in +0.5i +# cd $PCP_PMDAS_DIR/hotproc +# ./Install +.in +.fi +.ft 1 +.PP +If you want to undo the installation, do the following as root: +.PP +.ft CW +.nf +.in +0.5i +# cd $PCP_PMDAS_DIR/hotproc +# ./Remove +.in +.fi +.ft 1 +.PP +.B pmdahotproc +is launched by +.BR pmcd (1) +and should never be executed directly. +The Install and Remove scripts notify +.BR pmcd (1) +when the agent is installed or removed. +.SH FILES +.PD 0 +.TP 10 +.B $PCP_PMCDCONF_PATH +command line options used to launch +.B pmdahotproc +.TP 10 +.B /tmp/pcp.ttymap +tty map file used for hotproc.psinfo.ttyname +.TP 10 +.B $PCP_PMDAS_DIR/hotproc/help +default help text file for the Hotproc metrics +.TP 10 +.B $PCP_PMDAS_DIR/hotproc/Install +installation script for the +.B pmdahotproc +agent +.TP 10 +.B $PCP_PMDAS_DIR/hotproc/Remove +undo installation script for the +.B pmdahotproc +agent +.TP 10 +.B $PCP_PMDAS_DIR/hotproc/sample.conf +simple sample configuration (this is the default one) +.TP 10 +.B $PCP_PMDAS_DIR/hotproc/general.conf +another sample configuration that identifies "interesting" +processes from several different classes. +.TP 10 +.B $PCP_VAR_DIR/config/hotproc/hotproc.conf +predicate configuration file from the most recent installation +of the +.B pmdahotproc +agent +.TP 10 +.B $PCP_LOG_DIR/pmcd/hotproc.log +default log file for error messages and other information from +.B pmdahotproc +.PD +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.B /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). +.SH SEE ALSO +.BR PCPIntro (1), +.BR pmcd (1) +and +.BR pmstore (1). +.SH CAVEATS +Some of the required metrics may not be available on some platforms and these +will generate an error +message on startup. +.P +The values for hotproc.psinfo.ttyname are extracted from +.B /tmp/pcp.ttymap +which is created on the very first fetch of proc.psinfo.ttyname or +hotproc.psinfo.ttyname. +If new tty's are created past the high-water mark in /dev, then +this file will be out of date. To fix this, +.B /tmp/pcp.ttymap +should be removed and pmcd restarted ($PCP_RC_DIR/pcp start); +this will create a new tty map file. diff --git a/man/retired/pmnscomp.1 b/man/retired/pmnscomp.1 new file mode 100644 index 0000000..48923eb --- /dev/null +++ b/man/retired/pmnscomp.1 @@ -0,0 +1,185 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000-2004 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMNSCOMP 1 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmnscomp\f1 \- compile an ASCII performance metrics namespace into binary format. +.\" literals use .B or \f3 +.\" arguments use .I or \f2 +.SH SYNOPSIS +\f3pmnscomp\f1 +[\f3\-d\f1] +[\f3\-f\f1] +[\f3\-n\f1 \f2namespace\f1] +[\f3\-v\f1 \f2version\f1] +\f2outfile\f1 +.SH DESCRIPTION +.B pmnscomp +compiles a Performance Metrics Name Space (PMNS) in ASCII format into a more +efficient binary representation. +.BR pmLoadNameSpace (3) +is able to load this binary representation significantly faster than the +equivalent ASCII representation. +.PP +If +.I outfile +already exists +.B pmnscomp +will exit without overwriting it. +.PP +By convention, the name of the compiled namespace is that of the root file of +the ASCII namespace, with +.B .bin +appended. For example, the root of the default PMNS is a file named +.B root +and the compiled version of the entire namespace is +.BR root.bin . +.PP +The options are; +.TP 5 +.B \-d +By default the PMNS to be compiled is expected to contain at most one +name for each unique Performance Metric Id (PMID). The +.B \-d +option relaxes this restriction and allows the compilation of a +PMNS in which multiple names may be associated with a single PMID. +Duplicate names are useful when a particular metric may +be logically associated with more than one group of related metrics, +or when it is desired to create abbreviated aliases to name a set +of frequently used metrics. +.TP +.B \-f +Force overwriting of an existing +.I outfile +if it already exists. +.TP +.B \-n +Normally +.B pmnscomp +operates on the default PMNS, however if the +.B \-n +option is specified an alternative namespace is loaded +from the file +.IR namespace. +.TP +.B \-v +By default, +.B pmnscomp +writes a version +.B 2 +compiled namespace. +If +.I version +is +.B 1 +then +.B pmnscomp +will write a version +.B 1 +namespace which is similar to version +.BR 2 , +without the extra integrity afforded by checksums. +Note that PCP version 2.0 or later can handle both versions +.B 1 +and +.B 2 +of the binary PMNS format. +.PP +The default input PMNS is found in the file +.I $PCP_VAR_DIR/pmns/root +unless the environment variable +.B PMNS_DEFAULT +is set, in which case the value is assumed to be the pathname +to the file containing the default input PMNS. +.SH CAVEAT +Once the writing of the new +.I outfile +has begun, the signals SIGINT, SIGHUP and SIGTERM will be ignored +to protect the integrity of the new file. +.SH FILES +.PD 0 +.TP 10 +.I $PCP_VAR_DIR/pmns/* +default PMNS specification files +.TP +.I $PCP_VAR_DIR/pmns/root.bin +compiled version of the default PMNS, when the environment variable +.B PMNS_DEFAULT +is unset +.TP +.I $PCP_VAR_DIR/pmns/stdpmid +some standard macros for PMID generation +.PD +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.I /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). +.SH SEE ALSO +.BR pmnsadd (1), +.BR pmnsdel (1), +.BR pmnsmerge (1), +.BR PMAPI (3), +.BR pmLoadNameSpace (3), +.BR pcp.conf (5), +.BR pcp.env (5) +and +.BR pmns (5). +.SH DIAGNOSTICS +Cannot open ``xyz'' \- the filename for the root of the PMNS that was +passed to +.BR pmLoadNameSpace (3) +is bogus. +.PP +Illegal PMID \- either one of the three PMID components (see +.BR pmns (5)) +is not an integer, or the value for one of the +components is negative, or too large. +.PP +Expected ... \- specific syntax errors when a particular type of +lexical symbol was expected and +not found; the messages are intended to be self-explanatory. +.PP +Internal botch \- implementation problem for the parser ... +.PP +Duplicate name ``abc'' in subtree for ``pqr.xyz'' \- for each non-leaf +node, the names of all immediate descendents must be unique. +.PP +No name space entry for ``root'' \- the special non-leaf node with a pathname +of ``root'' defines the root of the PMNS, and must appear +somewhere in the PMNS specification. +.PP +Multiple name space entries for ``root'' \- more than one ``root'' node +does not make sense! +.PP +Disconnected subtree (``abc.xyz.def'') in name space \- the pathname +for this non-leaf node does not correspond to any pathname in the PMNS, +hence this non-leaf node is ``orphaned'' in the PMNS. +.PP +Cannot find definition for non-terminal node ``xyz'' in name space \- a +non-terminal node is named as part of its parent's specification, but +is never defined. +.PP +Duplicate metric id (xxx) in name space for metrics ``abc'' and ``xyz'' +\- each PMID must be unique across the PMNS. diff --git a/man/retired/pmtop.1 b/man/retired/pmtop.1 new file mode 100644 index 0000000..14a3215 --- /dev/null +++ b/man/retired/pmtop.1 @@ -0,0 +1,147 @@ +'\"macro stdmacro +.TH PMTOP 1 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmtop\f1 \- report top process resource usage +.SH SYNOPSIS +\f3pmtop\f1 +[\f3\-h\f1 \f2host\f1] +[\f3\-m\f1 \f2top\f1] +[\f3\-p\f1 \f2spec,...\f1] +[\f3\-s\f1 \f2samples\f1] +[\f3\-t\f1 \f2interval\f1] +[\f3\-w\f1] +[\f3\-z\f1] +[\f3\-Z\f1 \f2timezone\f1] +.SH DESCRIPTION +.B pmtop +reports per-process resource usage statistics +within the Performance Co-Pilot framework. +It outputs the highest \f2top\f1 values for the process +resources of cpu utilization, system calls per second, +context switches per second, kilobytes of data written per second, +kilobytes of data read per second and resident set size. +A subset of this information may be selected using the +.B \-p +option. +.SH COMMAND LINE OPTIONS +The command line options for +.B pmtop +are as follows: +.TP +\f3\-h\f1 \f2host\f1 +Fetch performance metrics from +.BR pmcd (1) +on +.IR host , +rather than the default local:. +.TP +\f3\-m\f1 \f2top\f1 +Report the \f2top\f1 highest values for a particular process +resource category. +The default is the top 5. +.TP +\f3\-p\f1 \f2spec,...\f1 +Print out the process resource categories specified in the list of +\f2spec\f1s. The specification is constructed from a comma +separated list of categories from the following set: +\f3cpu\f1, \f3sysc\f1, \f3ctx\f1, \f3read\f1, +\f3write\f1 and \f3rss\f1. +For example, "\f3\-p\f1 \f3cpu,ctx,rss\f1", will show +three reports for the categories of cpu utilization, context switches and +resident memory. It will also only show the category columns +of \f3CPU%\f1, \f3CTX\f1 and \f3RSS\f1. +The default is to display all the categories. +.TP +\f3\-s\f1 \f2samples\f1 +Determines how many samples (iterations) of process data +are displayed. +The default is to do an infinite number of samples. +.TP +\f3\-t\f1 \f2interval\f1 +This value is used to determine the interval between fetching +process data and reporting it. +The +.I interval +argument follows the syntax described in +.BR PCPIntro (1), +and in the simplest form may be an unsigned integer (the implied +units in this case are seconds). +The default is 2 seconds. +.TP +\f3\-w\f1 +Normally the report is truncated at the 80th column. +This option relieves this restriction. +.TP +\f3\-Z\f1 \f2timezone\f1 +By default, +.B pmtop +reports the time of day according to the local timezone on the system where +.B pmtop +is run. The +.B \-Z +option changes the default timezone to +.I timezone +which should be in the format of the environment variable +.B TZ +as described in +.BR environ (5). +.TP +\f3\-z\f1 +Change the reporting timezone to the local timezone at the host that is the +source of the performance metrics, as identified via the +.B \-h +option. +.SH "REPORT FORMAT" +.PP +The report is divided up into a number of sections, one for each +process category as specified by the +.B \-p +option. +This also affects which columns are displayed. +.P +At the top of the CPU%, SYSCALLS and CTX sections +it specifies how much the top +processes used of the resource compared with how much was +used globally by all the processes over the interval. +For example, for the +CPU utilization category looking at the top 5 processes, +a value of 90% indicates that the top 5 processes account +for 90% of the cpu consumption, the other 10% is used by processes +which are not shown. These other processes are either not +in the top 5, started after the beginning of the interval or +exited before the end of the interval. +.PP +The columns in the report should be interpreted as follows: +.PP +.TP 10 +.B PID +Process ID. +.TP +.B CPU% +Percentage of CPU Utilization. +.TP +.B SYSCALLS +The number of system calls per second. +.TP +.B CTX +The number of context switches per second. +.TP +.B WRITES +The number of kilobytes of data written per second. +.TP +.B READS +The number of kilobytes of data read per second. +.TP +.B RSS +The current resident set size in kilobytes. +.TP +.B CMD +The command and arguments, truncated so each line in the +report is at most 80 columns (unless the +.B \-w +option is given). +.SH SEE ALSO +.BR pmcd (1), +.BR pmem (1) +and +.BR pminfo (1). |
