Debian 3.9.10debian/3.9.10debian

1 files changed, 743 insertions, 0 deletions

diff --git a/man/man3/pmda.3 b/man/man3/pmda.3
new file mode 100644
index 0000000..20194f6
--- /dev/null
+++ b/man/man3/pmda.3
@@ -0,0 +1,743 @@
+'\"macro stdmacro
+.\"
+.\" Copyright (c) 2000-2004 Silicon Graphics, Inc.  All Rights Reserved.
+.\" 
+.\" This program is free software; you can redistribute it and/or modify it
+.\" under the terms of the GNU General Public License as published by the
+.\" Free Software Foundation; either version 2 of the License, or (at your
+.\" option) any later version.
+.\" 
+.\" This program is distributed in the hope that it will be useful, but
+.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
+.\" or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+.\" for more details.
+.\" 
+.\"
+.\" add in the -me strings for super and subscripts
+.ie n \{\
+.       ds [ \u\x'-0.25v'
+.       ds ] \d
+.       ds { \d\x'0.25v'
+.       ds } \u
+.\}
+.el \{\
+.       ds [ \v'-0.4m'\x'-0.2m'\s-3
+.       ds ] \s0\v'0.4m'
+.       ds { \v'0.4m'\x'0.2m'\s-3
+.       ds } \s0\v'-0.4m'
+.\}
+.TH PMDA 3 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3PMDA\f1 \- introduction to the Performance Metrics Domain Agent support library
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.br
+#include <pcp/impl.h>
+.br
+#include <pcp/pmda.h>
+.sp
+cc ... \-lpcp_pmda \-lpcp
+.ft 1
+.SH DESCRIPTION
+.de CW
+.ie t \f(CW\\$1\f1\\$2
+.el \fI\\$1\f1\\$2
+..
+To assist in the development of Performance Metric Domain Agents 
+.RB ( PMDA s)
+for the Performance Co-Pilot (PCP),
+a procedural interface is provided that extends the Performance Metrics
+Application Programming Interface (
+.BR PMAPI (3)) 
+library.  These procedures are designed to enable a programmer to quickly 
+build a 
+.B PMDA
+which can then be tested and refined.  However, this also 
+implies that a 
+.B PMDA
+has a particular structure which may not be suitable for 
+all applications.
+.PP
+Once you are familiar with the PCP and
+.B PMDA
+frameworks, you can quickly implement a new 
+.B PMDA
+with only a few data structures and functions.  This is covered in far greater
+detail in the
+.IR "Performance Co-Pilot Programmer's Guide" .
+.PP
+A
+.B PMDA
+is responsible for a set of performance metrics, in the sense that it must
+respond to requests from
+.BR pmcd(1)
+for information about performance metrics, instance domains, and instantiated
+values.  The
+.BR pmcd (1)
+process generates requests on behalf of performance tools that make requests
+using 
+.BR PMAPI (3)
+routines.
+.PP
+This man page contains sections of the 
+.B simple PMDA
+which is located at
+.IR $PCP_PMDAS_DIR/simple .
+.SH COMMUNICATING WITH PMCD
+Two approaches may be used for connecting a
+.B PMDA 
+to a 
+.BR pmcd (1)
+process.  A Dynamic Shared Object (DSO) can be attached by
+.BR pmcd (1)
+using
+.BR dlopen (3)
+when the
+.BR pmcd (1)
+process is started.  A procedural interface referenced through a shared data
+structure is used to handle requests from
+.BR pmcd (1)
+to the
+.BR PMDA .
+.PP
+The preferred approach is for a separate process (daemon) to communicate with 
+.BR pmcd (1)
+using the Performance Data Units (PDU) Inter-Process Communication (IPC)
+protocol.
+.PP
+All
+.BR PMDA s
+are launched and controlled by the
+.BR pmcd (1)
+process on the local host.  The requests from the clients are received by
+.BR pmcd (1)
+and forwarded to the appropriate
+.BR PMDA s.
+Responses, when required, are returned through 
+.BR pmcd (1)
+to the clients.  The requests (PDUs) that may be sent to a
+.B PMDA
+from
+.BR pmcd (1)
+are
+.BR PDU_FETCH ,
+.BR PDU_PROFILE ,
+.BR PDU_INSTANCE_REQ ,
+.BR PDU_DESC_REQ ,
+.BR PDU_TEXT_REQ 
+and
+.BR PDU_RESULT .
+.SH DEFAULT CALLBACKS FOR HANDLING PDUs
+To allow a consistent framework,
+.BR pmdaMain (3)
+can be used by a daemon
+.B PMDA
+to handle the communication protocol using the same callbacks as a DSO
+.BR PMDA .
+The structure
+.B pmdaInterface
+is used to convey the common procedural interface and state information that is
+used by 
+.BR pmcd (1)
+and a
+.BR PMDA .
+This state information includes tables describing the supported metrics and
+instance domains.
+.PP
+As most of the
+procedural interface is identical for all 
+.BR PMDA s,
+they are provided as part of
+this support library
+.RB ( pmdaProfile (3),
+.BR pmdaFetch (3),
+.BR pmdaInstance (3),
+.BR pmdaDesc (3),
+.BR pmdaText (3)
+and
+.BR pmdaStore (3)). 
+However, these routines require access to the 
+.B pmdaInterface
+state information so it must be correctly initialized using 
+.BR pmdaConnect (3),
+.BR pmdaDaemon (3),
+.BR pmdaOpenLog (3),
+.BR pmdaDSO (3),
+.BR pmdaGetOpt (3)
+and
+.BR pmdaInit (3).
+.SH INSTANCES AND INSTANCE DOMAINS
+Three structures are declared in
+.I /usr/include/pcp/pmda.h
+which provide a framework for declaring the metrics and instances supported by
+the 
+.BR PMDA .
+.PP
+Every instance requires a unique integer identifier and a unique name, as defined by
+the structure
+.BR pmdaInstid :
+.PP
+.nf
+.ft CW
+.in +0.5i
+/*
+ * Instance description: index and name
+ */
+
+typedef struct {
+    int         i_inst;        /* internal instance identifier */
+    char        *i_name;       /* external instance identifier */
+} pmdaInstid;
+.in
+.fi
+.PP
+An instance domain requires its own unique identification
+.RB ( pmInDom ),
+the number of instances the domain represents, and a pointer to an array of
+instance descriptions.  This is defined in the structure 
+.BR pmdaIndom :
+.PP
+.nf
+.ft CW
+.in +0.5i
+/*
+ * Instance domain description: unique instance id, 
+ * number of instances in this domain, and the list of 
+ * instances (not null terminated).
+ */
+
+typedef struct {
+    pmInDom     it_indom;       /* indom, filled in */
+    int         it_numinst;     /* number of instances */
+    pmdaInstid  *it_set;        /* instance identifiers */
+} pmdaIndom;
+.in
+.fi
+.ft 1
+.PP
+The
+.B simple PMDA 
+has one instance domain for 
+.IR simple . color
+with three instances
+.RI ( red ,
+.I green 
+and
+.IR blue ),
+and a second instance domain for
+.IR simple . now
+with instances which can be specified at run-time.
+These instance domains are defined as:
+.PP
+.nf
+.ft CW
+.in +0.5i
+static pmdaInstid _color[] = {
+    { 0, "red" }, { 1, "green" }, { 2, "blue" }
+};
+static pmdaInstid *_timenow = NULL;
+
+static pmdaIndom indomtab[] = {
+#define COLOR_INDOM	0
+    { COLOR_INDOM, 3, _color },
+#define NOW_INDOM 1
+    { NOW_INDOM, 0, NULL },
+};
+.in
+.fi
+.PP
+The preprocessor macros
+.B COLOR_INDOM
+and
+.B NOW_INDOM
+are used in the metric description table to identify the instance domains of
+individual metrics.  These correspond to the
+.I serial
+value in the instance domain 
+.B pmInDom
+structure (the 
+.I domain
+field is set by
+.BR pmdaInit (3)
+at run-time).  The serial value must be unique for each instance domain
+within the
+.BR PMDA . 
+.PP
+The indom table shown above which is usually passed to 
+.BR pmdaInit (3)
+does not need to be created 
+if one wants to write one's own Fetch and Instance functions.
+See 
+.BR pmdaInit (3)
+for more details.
+.SH NAMESPACE
+Every 
+.B PMDA
+has its own unique 
+.B namespace 
+using the format defined in 
+.BR pmns (5). 
+In summary, the namespace matches the names of the metrics to the unique
+identifier.  The
+.B simple PMDA
+defines five metrics:
+.IR simple . numfetch ,
+.IR simple . color ,
+.IR simple . time . user,
+.IR simple . time . sys
+and
+.IR simple . now .
+The namespace for these metrics is defined in
+.I $PCP_PMDAS_DIR/simple/pmns
+and is installed as:
+.PP
+.nf
+.ft CW
+.in +0.5in
+simple {
+    numfetch    253:0:0
+    color       253:0:1
+    time
+    now         253:2:4
+}
+
+simple.time {
+    user        253:1:2
+    sys         253:1:3
+}
+.in
+.fi
+.PP
+The domain number of
+.I 253
+is obtained from
+.IR $PCP_VAR_DIR/pmns/stdpmid .
+New 
+.BR PMDA s
+should specify a unique domain number in this file, and obtain the
+number during installation.  This allows the domain number to change by
+modifying only the file
+.IR $PCP_VAR_DIR/pmns/stdpmid .
+.PP
+The
+.I simple.time
+and
+.I simple.now
+metrics are defined in separate clusters to the other metrics which allows a
+.B PMDA
+to support more than 1024 metrics, as well as grouping similar metrics 
+together.  Therefore, the item numbers for a new cluster may be identical to 
+the item numbers in other clusters.  The 
+.B simple PMDA 
+continues to increment the item numbers to permit direct mapping (see
+.BR pmdaInit (3)).
+.PP
+The namespace file should be installed and removed with the agent using 
+.BR pmnsadd (1)
+and
+.BR pmnsdel (1).
+See the later sections on INSTALLATION and REMOVAL.
+.PP
+A simple ASCII namespace can be constructed by creating a file similar to
+.IR $PCP_PMDAS_DIR/simple/root :
+.PP
+.nf
+.ft CW
+.in +0.5i
+/*
+ * fake "root" for validating the local PMNS subtree
+ */
+
+#include "$PCP_VAR_DIR/pmns/stdpmid"
+
+root { simple }
+
+#include "pmns"
+
+.in
+.fi
+.PP
+and can be referred to with the
+.B \-n
+option in most PCP tools.
+.SH METRIC DESCRIPTIONS
+Each metric requires a description
+.RB ( pmDesc ), 
+which contains its PMID, data type specification, instance domain, semantics 
+and units (see 
+.BR pmLookupDesc (3)).
+A handle is also provided for application specific information in the
+.B pmdaMetric
+structure:
+.PP
+.nf
+.ft CW
+.in +0.5i
+/*
+ * Metric description: handle for extending description, 
+ * and the description.
+ */
+
+typedef struct {
+    void*       m_user;         /* for users external use */
+    pmDesc      m_desc;         /* metric description */
+} pmdaMetric;
+.in
+.fi
+.PP
+The 
+.B simple PMDA
+defines the metrics as:
+.PP
+.nf
+.ft CW
+.in +0.5i
+static pmdaMetric metrictab[] = {
+/* numfetch */
+    { (void *)0, 
+      { PMDA_PMID(0,0), PM_TYPE_U32, PM_INDOM_NULL, PM_SEM_INSTANT, 
+        { 0,0,0,0,0,0} }, },
+/* color */
+    { (void *)0, 
+      { PMDA_PMID(0,1), PM_TYPE_32, COLOR_INDOM, PM_SEM_INSTANT, 
+        { 0,0,0,0,0,0} }, },
+/* time.user */
+    { (void*)0,
+      { PMDA_PMID(1,2), PM_TYPE_DOUBLE, PM_INDOM_NULL, PM_SEM_COUNTER,
+      	{ 0, 1, 0, 0, PM_TIME_SEC, 0 } }, },
+/* time.sys */
+    { (void*)0,
+      { PMDA_PMID(1,3), PM_TYPE_DOUBLE, PM_INDOM_NULL, PM_SEM_COUNTER,
+      	{ 0, 1, 0, 0, PM_TIME_SEC, 0 } }, },
+/* now */
+    { NULL,
+      { PMDA_PMID(2,4), PM_TYPE_U32, NOW_INDOM, PM_SEM_INSTANT,
+        { 0,0,0,0,0,0 } }, },
+};
+.in
+.fi
+.PP
+The macro
+.B PMDA_PMID
+(defined in
+.IR /usr/include/pcp/pmda.h )
+is used to specify each metric's
+.I cluster
+and
+.I unit 
+number in the 
+.B __pmID_int
+structure defined in
+.IR /usr/include/pcp/impl.h .
+As with instance domains, the
+.I domain
+field is set by
+.BR pmdaInit (3)
+at run-time, however, the default domain is assumed to be defined by the
+.B PMDA 
+in the macro
+.BR MYDOMAIN .
+.PP
+The metric table shown above which is usually passed to 
+.BR pmdaInit (3)
+does not need to be created 
+if one wants to write one's own Fetch and Descriptor functions.
+See 
+.BR pmdaInit (3)
+for more details.
+.SH DSO PMDA
+A 
+.B PMDA
+that is run as a DSO is opened by 
+.BR pmcd (1)
+with
+.BR dlopen (3).
+.B pmcd
+will call the 
+.BR PMDA "'s"
+initialization function that is specified in
+.IR $PCP_PMCDCONF_PATH. 
+This function is passed a pointer to a
+.B pmdaInterface 
+structure which must be completed.  Any callbacks which are
+.I not
+the default 
+.B PMDA
+support library callbacks must be specified in the
+.B pmdaInterface
+structure. 
+.PP
+The
+.B simple PMDA 
+uses its own store and fetch callback.  
+.BR simple_fetch ()
+calls 
+.BR pmdaFetch (3)
+which requires a callback to be set with
+.BR pmdaSetFetchCallBack (3)
+as can be seen in
+.IR $PCP_PMDAS_DIR/simple/simple.c .
+.PP
+The flag
+.B _isDSO
+is used to determine if the 
+.B PMDA
+is a daemon or a DSO so that the correct initialization
+routine,
+.BR pmdaDaemon (3)
+or
+.BR pmdaDSO (3),
+is called.
+.SH DAEMON PMDA
+A 
+.B PMDA
+that is run as a daemon is forked and executed by 
+.BR pmcd (1).
+Therefore, unlike a DSO 
+.BR PMDA ,
+the starting point for a daemon 
+.B PMDA 
+is
+.BR main ().
+The agent should parse the command line arguments, create
+a log file and initialize some data structures that 
+.B pmcd
+would initialize for a DSO agent.
+.PP
+The
+.B pmdaInterface
+structure must be completely defined by the daemon
+.BR PMDA .
+The function
+.BR pmdaDaemon (3)
+can be called at the start of 
+.BR main ()
+to set most of these fields.  Command line parsing can be simplified by using
+.BR pmdaGetOpt (3),
+which is similar to 
+.BR getopt (2),
+but extracts a common set of options into the 
+.B pmdaInterface
+structure.
+.I stderr 
+can be mapped to a log file using 
+.BR pmdaOpenLog (3)
+to simplify debugging and error messages.  The connection to 
+.B pmcd
+can be made with
+.BR pmdaConnect (3)
+and the loop which handles the incoming PDUs,
+.BR pmdaMain (3),
+should be the last function called.  This can be seen in
+.IR $PCP_PMDAS_DIR/simple/simple.c .
+.PP
+The
+.BR simple_init ()
+routine is common to an agent that can be run as both a Daemon and DSO
+.BR PMDA .
+.SH HELP TEXT
+Each 
+.B PMDA
+must be able to provide 
+.B pmcd
+with the help text for each metric.  Most 
+.BR PMDA s
+use specially created files with indexes to support
+efficient retrieval of the help text.
+Tools are provided with PCP to
+create the help text files of appropriate format. See 
+.BR newhelp (1).
+.SH INSTALLATION AND REMOVAL
+A series of shell procedures are defined in 
+.I $PCP_SHARE_DIR/lib/pmdaproc.sh 
+which greatly simplify the installation and removal of a
+.BR PMDA .
+The
+.I Install
+scripts for most
+.BR PMDAs
+should only need to specify the name of the
+.B PMDA
+in
+.BR iam ,
+call
+.B _setup
+which check licenses and whether the 
+.B PMDA
+has been previously installed,
+specify the communication protocols,
+and finally call
+.BR _install .
+The 
+.I Remove
+scripts are even simpler as the communication protocols are not required.
+Further information is contained in the
+.I $PCP_SHARE_DIR/lib/pmdaproc.sh
+file.
+.SH DIAGNOSTICS
+Any 
+.B PMDA
+which uses this library can set
+.BR PMAPI (3)
+debug control variable
+.B pmDebug
+(with \-D on the command line) to 
+.B DBG_TRACE_LIBPMDA
+to enable the display of debugging information which may be useful during
+development
+(see
+.BR pmdbg (1)).
+.PP
+The
+.I status 
+field of the 
+.B pmdaInterface
+structure should be zero after 
+.BR pmdaDaemon ,
+.BR pmdaDSO ,
+.BR pmdaGetOpt ,
+.BR pmdaConnect
+and
+.B pmdaInit
+are called.  A value less than zero indicates that initialization has failed.
+.PP
+Some error messages that are common to most functions in this library are:
+.TP 15
+.BI "PMDA interface version " interface " not supported"
+Most of the functions require that the
+.I comm.version
+field of the
+.B pmdaInterface
+structure be set to
+.B PMDA_INTERFACE_2
+or later.
+.B PMDA_INTERFACE_2
+or
+.B PMDA_INTERFACE_3
+implies that the 
+.I version.two
+fields are correctly initialized,
+while
+.B PMDA_INTERFACE_4
+implies that the 
+.I version.four
+fields are correctly initialized
+(see
+.BR pmdaDaemon (3)
+and
+.BR pmdaDSO (3)).
+.SH CAVEAT
+Failing to complete any of the data structures or calling any of the library
+routines out of order may cause unexpected behavior in the
+.BR PMDA .
+.PP
+Due to changes to the
+.BR PMAPI (3)
+and
+.BR PMDA (3)
+API in the PCP 2.0 release, as described in the product release notes, 
+.BR PMDA s
+built using PCP 2.0 must specify 
+.B PMDA_INTERFACE_2
+or later and link with
+.I libpcp_pmda.so.2
+and
+.IR libpcp.so.2 .
+Pre-existing Daemon PMDAs specifying 
+.B PMDA_PROTOCOL_1
+will continue to function using the backwards compatible 
+.I libpcp_pmda.so.1
+and
+.I libpcp.so.1
+libraries and may be recompiled using the headers installed in
+.I "/usr/include/pcp1.x/"
+without any modification.  These backwards compatible headers and libraries
+are contained in the
+.I pcp.sw.compat
+subsystem.
+.SH FILES
+.TP 10
+.I /usr/include/pcp/pmda.h
+Header file for the 
+.B PMDA
+support library.
+.TP
+.I /usr/lib/libpcp_pmda.so
+Dynamic library containing 
+.B PMDA 
+support library routines.
+.TP
+.I $PCP_PMDAS_DIR/trivial
+The source of the
+.BR "trivial PMDA" .
+.TP
+.I $PCP_PMDAS_DIR/simple
+The source of the
+.BR "simple PMDA" .
+.TP
+.I $PCP_PMDAS_DIR/txmon
+The source of the
+.BR "txmon PMDA" .
+.TP
+.I $PCP_PMCDCONF_PATH
+Configuration file for
+.BR pmcd (1).
+.TP
+.I $PCP_VAR_DIR/pmns
+Location of namespace descriptions for every
+.BR PMDA .
+.TP
+.I $PCP_VAR_DIR/pmns/stdpmid
+The unique domain identifiers for each
+.BR PMDA .
+.TP
+.I $PCP_SHARE_DIR/lib/pmdaproc.sh
+Shell procedures for installing and removing a
+.BR PMDA .
+.SH "PCP ENVIRONMENT"
+Environment variables with the prefix
+.B PCP_
+are used to parameterize the file and directory names
+used by PCP.
+On each installation, the file
+.I /etc/pcp.conf
+contains the local values for these variables.
+The
+.B $PCP_CONF
+variable may be used to specify an alternative
+configuration file,
+as described in
+.BR pcp.conf (5).
+Values for these variables may be obtained programmatically
+using the
+.IR pmGetConfig (3)
+function.
+.SH SEE ALSO
+.BR dbpmda (1),
+.BR newhelp (1),
+.BR pmcd (1),
+.BR pmnsadd (1),
+.BR pmnsdel (1),
+.BR PMAPI (3),
+.BR pmdaConnect (3),
+.BR pmdaDaemon (3),
+.BR pmdaDesc (3),
+.BR pmdaDSO (3),
+.BR pmdaFetch (3),
+.BR pmdaGetOpt (3),
+.BR pmdaInit (3),
+.BR pmdaInstance (3),
+.BR pmdaMain (3),
+.BR pmdaOpenLog (3),
+.BR pmdaProfile (3),
+.BR pmdaStore (3),
+.BR pmdaText (3),
+.BR pmLookupDesc (3)
+and
+.BR pmns (5).
+.PP
+For a complete description of the
+.I pcp_pmda
+library and the PMDA development process, refer to the Insight book
+.IR "Performance Co-Pilot Programmer's Guide" .