diff options
Diffstat (limited to 'man/man1')
103 files changed, 25955 insertions, 0 deletions
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). |