Provided by: libpcp-pmda3-dev_2.8.12_i386 bug

NAME

       PMDA  -  introduction  to  the Performance Metrics Domain Agent support
       library

C SYNOPSIS

       #include <pcp/pmapi.h>
       #include <pcp/impl.h>
       #include <pcp/pmda.h>

       cc ... -lpcp_pmda -lpcp

DESCRIPTION

       To assist in  the  development  of  Performance  Metric  Domain  Agents
       (PMDAs)  for  the Performance Co-Pilot (PCP), a procedural interface is
       provided that extends the Performance Metrics  Application  Programming
       Interface ( PMAPI(3)) library.  These procedures are designed to enable
       a programmer to quickly build a PMDA  which  can  then  be  tested  and
       refined.   However,  this  also  implies  that  a PMDA has a particular
       structure which may not be suitable for all applications.

       Once you are familiar with the PCP and PMDA frameworks, you can quickly
       implement  a  new  PMDA  with only a few data structures and functions.
       This is covered in far  greater  detail  in  the  Performance  Co-Pilot
       Programmer’s Guide.

       A  PMDA  is  responsible for a set of performance metrics, in the sense
       that it must respond to requests from  pmcd(1)  for  information  about
       performance  metrics,  instance  domains, and instantiated values.  The
       pmcd(1) process generates requests on behalf of performance tools  that
       make requests using PMAPI(3) routines.

       This  man page contains sections of the simple PMDA which is located at
       $PCP_PMDAS_DIR/simple.

COMMUNICATING WITH PMCD

       Two approaches may be used for connecting a PMDA to a pmcd(1)  process.
       A  Dynamic  Shared  Object  (DSO)  can  be  attached  by  pmcd(1) using
       dlopen(3) when the pmcd(1) process is started.  A procedural  interface
       referenced  through  a shared data structure is used to handle requests
       from pmcd(1) to the PMDA.

       The  preferred  approach  is  for  a  separate  process   (daemon)   to
       communicate  with pmcd(1) using the Performance Data Units (PDU) Inter-
       Process Communication (IPC) protocol.

       All PMDAs are launched and controlled by the  pmcd(1)  process  on  the
       local  host.  The requests from the clients are received by pmcd(1) and
       forwarded to the appropriate  PMDAs.   Responses,  when  required,  are
       returned  through pmcd(1) to the clients.  The requests (PDUs) that may
       be  sent  to  a  PMDA  from   pmcd(1)   are   PDU_FETCH,   PDU_PROFILE,
       PDU_INSTANCE_REQ, PDU_DESC_REQ, PDU_TEXT_REQ and PDU_RESULT.

DEFAULT CALLBACKS FOR HANDLING PDUs

       To  allow  a  consistent framework, pmdaMain(3) can be used by a daemon
       PMDA to handle the communication protocol using the same callbacks as a
       DSO  PMDA.   The  structure  pmdaInterface is used to convey the common
       procedural interface and state information that is used by pmcd(1)  and
       a   PMDA.   This  state  information  includes  tables  describing  the
       supported metrics and instance domains.

       As most of the procedural interface is identical for  all  PMDAs,  they
       are   provided   as  part  of  this  support  library  (pmdaProfile(3),
       pmdaFetch(3),    pmdaInstance(3),    pmdaDesc(3),    pmdaText(3)    and
       pmdaStore(3)).    However,   these   routines  require  access  to  the
       pmdaInterface state information so it  must  be  correctly  initialized
       using   pmdaConnect(3),   pmdaDaemon(3),   pmdaOpenLog(3),  pmdaDSO(3),
       pmdaGetOpt(3) and pmdaInit(3).

INSTANCES AND INSTANCE DOMAINS

       Three structures are declared in /usr/include/pcp/pmda.h which  provide
       a  framework  for  declaring the metrics and instances supported by the
       PMDA.

       Every instance requires a unique integer identifier and a unique  name,
       as defined by the structure pmdaInstid:

            /*
             * Instance description: index and name
             */

            typedef struct {
                int         i_inst;        /* internal instance identifier */
                char        *i_name;       /* external instance identifier */
            } pmdaInstid;

       An  instance  domain  requires its own unique identification (pmInDom),
       the number of instances the domain represents,  and  a  pointer  to  an
       array  of  instance  descriptions.   This  is  defined in the structure
       pmdaIndom:

            /*
             * 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;

       The simple PMDA has one instance domain  for  simple.color  with  three
       instances  (red,  green  and  blue),  and  a second instance domain for
       simple.now with instances which can be specified  at  run-time.   These
       instance domains are defined as:

            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 },
            };

       The  preprocessor  macros  COLOR_INDOM  and  NOW_INDOM  are used in the
       metric description table to identify the instance domains of individual
       metrics.   These  correspond to the serial value in the instance domain
       pmInDom structure (the domain field is set by pmdaInit(3) at run-time).
       The  serial  value  must  be unique for each instance domain within the
       PMDA.

       The indom table shown above which is usually passed to pmdaInit(3) does
       not  need  to  be  created  if  one  wants to write one’s own Fetch and
       Instance functions.  See pmdaInit(3) for more details.

NAMESPACE

       Every PMDA has its own unique namespace using  the  format  defined  in
       pmns(4).  In summary, the namespace matches the names of the metrics to
       the  unique  identifier.   The  simple  PMDA  defines   five   metrics:
       simple.numfetch,  simple.color,  simple.time.user,  simple.time.sys and
       simple.now.   The  namespace  for   these   metrics   is   defined   in
       $PCP_PMDAS_DIR/simple/pmns and is installed as:

            simple {
                numfetch    253:0:0
                color       253:0:1
                time
                now         253:2:4
            }

            simple.time {
                user        253:1:2
                sys         253:1:3
            }

       The  domain  number  of 253 is obtained from $PCP_VAR_DIR/pmns/stdpmid.
       New PMDAs 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 $PCP_VAR_DIR/pmns/stdpmid.

       The simple.time and simple.now metrics are defined in separate clusters
       to  the  other  metrics  which  allows a 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  simple  PMDA  continues  to  increment  the  item
       numbers to permit direct mapping (see pmdaInit(3)).

       The namespace file should be installed and removed with the agent using
       pmnsadd(1) and pmnsdel(1).  See the later sections on INSTALLATION  and
       REMOVAL.

       A  simple ASCII namespace can be constructed by creating a file similar
       to $PCP_PMDAS_DIR/simple/root:

            /*
             * fake "root" for validating the local PMNS subtree
             */

            #include "$PCP_VAR_DIR/pmns/stdpmid"

            root { simple }

            #include "pmns"

       and can be referred to with the -n option in most PCP tools.

METRIC DESCRIPTIONS

       Each metric requires a description (pmDesc), which contains  its  PMID,
       data  type  specification,  instance  domain,  semantics and units (see
       pmLookupDesc(3)).  A handle is also provided for  application  specific
       information in the pmdaMetric structure:

            /*
             * Metric description: handle for extending description,
             * and the description.
             */

            typedef struct {
                void*       m_user;         /* for users external use */
                pmDesc      m_desc;         /* metric description */
            } pmdaMetric;

       The simple PMDA defines the metrics as:

            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 } }, },
            };

       The  macro  PMDA_PMID  (defined  in /usr/include/pcp/pmda.h) is used to
       specify each  metric’s  cluster  and  unit  number  in  the  __pmID_int
       structure   defined   in  /usr/include/pcp/impl.h.   As  with  instance
       domains, the domain field is set by pmdaInit(3) at  run-time,  however,
       the  default  domain  is assumed to be defined by the PMDA in the macro
       MYDOMAIN.

       The metric table shown above which is  usually  passed  to  pmdaInit(3)
       does  not  need to be created if one wants to write one’s own Fetch and
       Descriptor functions.  See pmdaInit(3) for more details.

DSO PMDA

       A PMDA that is run as a DSO is opened by pmcd(1) with dlopen(3).   pmcd
       will  call  the  PMDA’s  initialization  function  that is specified in
       $PCP_PMCDCONF_PATH.   This  function  is  passed   a   pointer   to   a
       pmdaInterface  structure  which must be completed.  Any callbacks which
       are not the default PMDA support library callbacks must be specified in
       the pmdaInterface structure.

       The  simple PMDA uses its own store and fetch callback.  simple_fetch()
       calls  pmdaFetch(3)  which  requires  a  callback  to   be   set   with
       pmdaSetFetchCallBack(3)       as       can       be       seen       in
       $PCP_PMDAS_DIR/simple/simple.c.

       The flag _isDSO is used to determine if the PMDA is a daemon or  a  DSO
       so   that   the   correct   initialization  routine,  pmdaDaemon(3)  or
       pmdaDSO(3), is called.

DAEMON PMDA

       A PMDA that is run as a daemon  is  forked  and  executed  by  pmcd(1).
       Therefore,  unlike  a DSO PMDA, the starting point for a daemon PMDA is
       main().  The agent should parse the command line  arguments,  create  a
       log file and initialize some data structures that pmcd would initialize
       for a DSO agent.

       The pmdaInterface structure must be completely defined  by  the  daemon
       PMDA.   The function pmdaDaemon(3) can be called at the start of main()
       to set most of these fields.  Command line parsing can be simplified by
       using  pmdaGetOpt(3),  which  is  similar  to getopt(2), but extracts a
       common set of options into the pmdaInterface structure.  stderr can  be
       mapped  to  a  log  file using pmdaOpenLog(3) to simplify debugging and
       error messages.  The connection to pmcd can be made with pmdaConnect(3)
       and  the  loop  which handles the incoming PDUs, pmdaMain(3), should be
       the    last    function    called.     This    can    be    seen     in
       $PCP_PMDAS_DIR/simple/simple.c.

       The simple_init() routine is common to an agent that can be run as both
       a Daemon and DSO PMDA.

HELP TEXT

       Each PMDA must be able to provide pmcd with  the  help  text  for  each
       metric.  Most PMDAs 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 newhelp(1).

INSTALLATION AND REMOVAL

       A     series     of     shell     procedures     are     defined     in
       $PCP_SHARE_DIR/lib/pmdaproc.sh which greatly simplify the  installation
       and  removal of a PMDA.  The Install scripts for most PMDAs should only
       need to specify the name of the PMDA in iam, call  _setup  which  check
       licenses  and  whether  the PMDA has been previously installed, specify
       the communication protocols, and finally  call  _install.   The  Remove
       scripts  are  even  simpler  as  the  communication  protocols  are not
       required.     Further    information    is     contained     in     the
       $PCP_SHARE_DIR/lib/pmdaproc.sh file.

DIAGNOSTICS

       Any  PMDA  which  uses  this  library  can  set  PMAPI(3) debug control
       variable pmDebug (with -D on the command line) to DBG_TRACE_LIBPMDA  to
       enable  the display of debugging information which may be useful during
       development (see pmdbg(1)).

       The status field of the pmdaInterface structure should  be  zero  after
       pmdaDaemon,  pmdaDSO,  pmdaGetOpt, pmdaConnect and pmdaInit are called.
       A value less than zero indicates that initialization has failed.

       Some error messages that are common to most functions in  this  library
       are:

       PMDA interface version interface not supported
                      Most  of  the  functions  require  that the comm.version
                      field  of  the  pmdaInterface  structure   be   set   to
                      PMDA_INTERFACE_2   or  later.   This  implies  that  the
                      version.two  fields  are  correctly   initialized   (see
                      pmdaDaemon(3) and pmdaDSO(3)).

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
       PMDA.

       Due  to changes to the PMAPI(3) and PMDA(3) API in the PCP 2.0 release,
       as described in the product release notes, PMDAs built  using  PCP  2.0
       must  specify  PMDA_INTERFACE_2 or later and link with libpcp_pmda.so.2
       and libpcp.so.2.  Pre-existing Daemon PMDAs specifying  PMDA_PROTOCOL_1
       will    continue   to   function   using   the   backwards   compatible
       libpcp_pmda.so.1 and libpcp.so.1 libraries and may be recompiled  using
       the headers installed in /usr/include/pcp1.x/ without any modification.
       These backwards compatible headers and libraries are contained  in  the
       pcp.sw.compat subsystem.

FILES

       /usr/include/pcp/pmda.h
                 Header file for the PMDA support library.

       /usr/lib/libpcp_pmda.so
                 Dynamic library containing PMDA support library routines.

       $PCP_PMDAS_DIR/trivial
                 The source of the trivial PMDA.

       $PCP_PMDAS_DIR/simple
                 The source of the simple PMDA.

       $PCP_PMDAS_DIR/txmon
                 The source of the txmon PMDA.

       $PCP_PMCDCONF_PATH
                 Configuration file for pmcd(1).

       $PCP_VAR_DIR/pmns
                 Location of namespace descriptions for every PMDA.

       $PCP_VAR_DIR/pmns/stdpmid
                 The unique domain identifiers for each PMDA.

       $PCP_SHARE_DIR/lib/pmdaproc.sh
                 Shell procedures for installing and removing a PMDA.

PCP ENVIRONMENT

       Environment variables with the prefix PCP_ are used to parameterize the
       file and directory names used by PCP.  On each installation,  the  file
       /etc/pcp.conf  contains  the  local  values  for  these variables.  The
       $PCP_CONF variable may be used to specify an alternative  configuration
       file,  as  described in pcp.conf(4).  Values for these variables may be
       obtained programatically using the pmGetConfig(3) function.

SEE ALSO

       dbpmda(1),  newhelp(1),  pmcd(1),  pmnsadd(1),  pmnsdel(1),   PMAPI(3),
       pmdaConnect(3),  pmdaDaemon(3),  pmdaDesc(3), pmdaDSO(3), pmdaFetch(3),
       pmdaGetOpt(3),     pmdaInit(3),      pmdaInstance(3),      pmdaMain(3),
       pmdaOpenLog(3),      pmdaProfile(3),     pmdaStore(3),     pmdaText(3),
       pmLookupDesc(3) and pmns(4).

       For a complete  description  of  the  pcp_pmda  library  and  the  PMDA
       development  process,  refer  to  the Insight book Performance Co-Pilot
       Programmer’s Guide.