Provided by: libpcp3-dev_3.2.0_i386 bug

NAME

       PMAPI - introduction to the Performance Metrics Application Programming
       Interface

C SYNOPSIS

       #include <pcp/pmapi.h>

        ... assorted routines ...

       cc ... -lpcp

DESCRIPTION

       Within  the  framework  of  the  Performance  Co-Pilot  (PCP),   client
       applications  are  developed  using the Performance Metrics Application
       Programming Interface (PMAPI) that defines a procedural interface  with
       services  suited  to  the development of applications with a particular
       interest in performance metrics.

       This description presents an overview of the PMAPI and the  context  in
       which PMAPI applications are run.  The PMAPI is more fully described in
       the Performance Co-Pilot Programmer’s Guide, and the manual  pages  for
       the individual PMAPI routines.

PERFORMANCE METRICS - NAMES AND IDENTIFIERS

       For  a  description  of  the  Performance Metrics Name Space (PMNS) and
       associated terms and concepts, see PCPIntro(1).

       Not all PMIDs need be represented in the  PMNS  of  every  application.
       For example, an application which monitors disk traffic will likely use
       a name space which references only the PMIDs for I/O statistics.

       Applications which use the PMAPI may have  independent  versions  of  a
       PMNS,  constructed  from  an  initialization  file when the application
       starts; see  pmLoadASCIINameSpace(3),  pmLoadNameSpace(3),  pmnscomp(1)
       and pmns(4).

       Internally  (below  the  PMAPI)  the  implementation of the Performance
       Metrics Collection System (PMCS)  uses  only  the  PMIDs,  and  a  PMNS
       provides  an  external  mapping  from a hierarchic taxonomy of names to
       PMIDs that is convenient in the  context  of  a  particular  system  or
       particular  use  of  the  PMAPI.   For the applications programmer, the
       routines pmLookupName(3) and pmNameID(3) translate between names  in  a
       PMNS  and  PMIDs,  and  vice  versa.   The  PMNS may be traversed using
       pmGetChildren(3).

PMAPI CONTEXT

       An application  using  the  PMAPI  may  manipulate  several  concurrent
       contexts,  each  associated  with a source of performance metrics, e.g.
       pmcd(1) on some host, or an  archive  log  of  performance  metrics  as
       created by pmlogger(1).

       Contexts  are identified by a ‘‘handle’’, a small integer value that is
       returned  when  the  context  is  created;  see   pmNewContext(3)   and
       pmDupContext(3).   Some  PMAPI functions require an explicit ‘‘handle’’
       to identify the correct context, but more commonly the  PMAPI  function
       is  executed  in  the  ‘‘current’’ context.  The current context may be
       discovered using pmWhichContext(3) and changed using pmUseContext(3).

       If a PMAPI context has not been explicitly established (or the previous
       current  context  has  been  closed using pmDestroyContext(3)) then the
       current PMAPI context is undefined.

       In addition to the source of the performance metrics, the context  also
       includes  the  instance  profile  and  collection  time (both described
       below) which controls how much information is returned,  and  when  the
       information was collected.

INSTANCE DOMAINS

       When  performance  metric  values  are  returned  across the PMAPI to a
       requesting application,  there  may  be  more  than  one  value  for  a
       particular  metric.  Multiple values, or instances, for a single metric
       are typically the result of instrumentation being implemented for  each
       instance  of  a set of similar components or services in a system, e.g.
       independent counts for each CPU, or each process, or each disk, or each
       system  call  type, etc.  This multiplicity of values is not enumerated
       in the name space but rather, when performance  metrics  are  delivered
       across  the  PMAPI by pmFetch(3), the format of the result accommodates
       values for one or more instances, with an instance-value pair  encoding
       the metric value for a particular instance.

       The  instances are identified by an internal identifier assigned by the
       agent responsible for  instantiating  the  values  for  the  associated
       performance  metric.   Each  instance  identifier  has  a corresponding
       external instance identifier name  (an  ASCII  string).   The  routines
       pmGetInDom(3),  pmLookupInDom(3)  and  pmNameInDom(3)  may  be  used to
       enumerate all instance identifiers, and to translate  between  internal
       and external instance identifiers.

       All of the instance identifiers for a particular performance metric are
       collectively known as an instance domain.  Multiple performance metrics
       may share the same instance domain.

       If  only  one  instance  is ever available for a particular performance
       metric, the instance identifier in the result from  pmFetch(3)  assumes
       the special value PM_IN_NULL and may be ignored by the application, and
       only one instance-value pair appears in the  result  for  that  metric.
       Under  these circumstances, the associated instance domain (as returned
       via pmLookupDesc(3)) is set to PM_INDOM_NULL to  indicate  that  values
       for this metric are singular.

       The  difficult  issue  of  transient  performance  metrics  (e.g.  per-
       filesystem information, hot-plug replaceable  hardware  modules,  etc.)
       means  that  repeated  requests  for the same PMID may return different
       numbers of values, and/or  some  changes  in  the  particular  instance
       identifiers  returned.   This  means applications need to be aware that
       metric  instantiation  is  guaranteed  to  be  valid  at  the  time  of
       collection only.  Similar rules apply to the transient semantics of the
       associated metric values.  In general however, it is expected that  the
       bulk  of the performance metrics will have instantiation semantics that
       are fixed over the execution life-time of any PMAPI client.

THE TYPE OF METRIC VALUES

       The PMAPI supports a wide range of format and type  encodings  for  the
       values  of  performance  metrics,  namely signed and unsigned integers,
       floating point numbers, 32-bit and  64-bit  encodings  of  all  of  the
       above,  ASCII  strings  (C-style,  NULL byte terminated), and arbitrary
       aggregates of binary data.

       The type field in the  pmDesc  structure  returned  by  pmLookupDesc(3)
       identifies  the  format  and  type  of  the  values  for  a  particular
       performance metric within a particular PMAPI context.

       Note that the encoding of values for a  particular  performance  metric
       may  be  different  for different PMAPI contexts, due to differences in
       the underlying implementation for different contexts.   However  it  is
       expected  that  the  vast  majority  of  performance  metrics will have
       consistent value encoding across all versions of  all  implementations,
       and hence across all PMAPI contexts.

       The  PMAPI  supports  routines  to automate the handling of the various
       value formats  and  types,  particularly  for  the  common  case  where
       conversion  to a canonical format is desired, see pmExtractValue(3) and
       pmPrintValue(3).

THE DIMENSIONALITY AND SCALE OF METRIC VALUES

       Independent of how the value is encoded, the value  for  a  performance
       metric  is  assumed  to  be  drawn  from  a  set  of values that can be
       described in terms of their  dimensionality  and  scale  by  a  compact
       encoding  as  follows.   The  dimensionality  is defined by a power, or
       index, in each of 3 orthogonal dimensions, namely Space, Time and Count
       (or Events, which are dimensionless).  For example I/O throughput might
       be represented as Space/Time, while the running total of  system  calls
       is  Count,  memory  allocation  is  Space  and  average service time is
       Time/Count.  In each dimension there  are  a  number  of  common  scale
       values  that  may  be used to better encode ranges that might otherwise
       exhaust the precision of a 32-bit value.  This information  is  encoded
       in  the  pmUnits  structure  which  is embedded in the pmDesc structure
       returned from pmLookupDesc(3).

       The routine pmConvScale(3) is provided to convert values in conjunction
       with  the  pmUnits structures that defines the dimensionality and scale
       of the values for a particular  performance  metric  as  returned  from
       pmFetch(3),  and  the desired dimensionality and scale of the value the
       PMAPI client wishes to manipulate.

INSTANCE PROFILE

       The set of instances for performance metrics returned from a pmFetch(3)
       call may be filtered or restricted using an instance profile.  There is
       one instance profile for each PMAPI context  the  application  creates,
       and  each  instance  profile  may  include  instances  from one or more
       instance domains.

       The  routines  pmAddProfile(3)  and  pmDelProfile(3)  may  be  used  to
       dynamically adjust the instance profile.

COLLECTION TIME

       For  each set of values for performance metrics returned via pmFetch(3)
       there is an associated ‘‘timestamp’’ that serves to identify  when  the
       performance  metric  values were collected; for metrics being delivered
       from a  real-time  source  (i.e.  pmcd(1)  on  some  host)  this  would
       typically  be  not long before they were exported across the PMAPI, and
       for metrics being delivered from an archive log, this would be the time
       when the metrics were written into the archive log.

       There is an issue here of exactly when individual metrics may have been
       collected, especially  given  their  origin  in  potentially  different
       Performance  Metric  Domains,  and  variability  in the metric updating
       frequency at the lowest level of the Performance  Metric  Domain.   The
       PMCS opts for the pragmatic approach, in which the PMAPI implementation
       undertakes to return all of the metrics with values accurate as of  the
       timestamp,  to  the  best  of  our  ability.   The  belief  is that the
       inaccuracy this introduces is  small,  and  the  additional  burden  of
       accurate  individual  timestamping  for  each  returned metric value is
       neither warranted nor practical (from an implementation viewpoint).

       Of course, in the case of collection of metrics from multiple hosts the
       PMAPI client must assume the sanity of the timestamps is constrained by
       the extent to which clock  synchronization  protocols  are  implemented
       across the network.

       A  PMAPI  application  may  call  pmSetMode(3)  to  vary  the requested
       collection time, e.g. to rescan performance  metrics  values  from  the
       recent past, or to ‘‘fast-forward’’ through an archive log.

GENERAL ISSUES OF PMAPI PROGRAMMING STYLE

       Across  the  PMAPI,  all  arguments  and  results involving a ‘‘list of
       something’’ are declared to be arrays with an  associated  argument  or
       function  value  to  identify the number of elements in the list.  This
       has been done to avoid  both  the  varargs(3)  approach  and  sentinel-
       terminated lists.

       Where  the  size  of a result is known at the time of a call, it is the
       caller’s responsibility to allocate (and possibly  free)  the  storage,
       and  the  called  function  will  assume  the  result argument is of an
       appropriate size.  Where a result is of variable  size  and  that  size
       cannot  be  known in advance (e.g. for pmGetChildren(3), pmGetInDom(3),
       pmNameInDom(3), pmNameID(3), pmLookupText(3) and pmFetch(3)) the  PMAPI
       implementation uses a range of dynamic allocation schemes in the called
       routine, with the caller responsible  for  subsequently  releasing  the
       storage  when  no  longer required.  In some cases this simply involves
       calls to free(3C), but in others (most  notably  for  the  result  from
       pmFetch(3)),  special routines (e.g. pmFreeResult(3)) should be used to
       release the storage.

       As a general rule, if the called routine returns an error  status  then
       no  allocation will have been done, and any pointer to a variable sized
       result is undefined.

DIAGNOSTICS

       Where error conditions may arise, the functions that comprise the PMAPI
       conform to a single, simple error notification scheme, as follows;

       +  the function returns an integer

       +  values  >=  0  indicate  no error, and perhaps some positive status,
          e.g. the number of things really processed

       +  values <  0  indicate  an  error,  with  a  global  table  of  error
          conditions and error messages

       The  PMAPI  routine  pmErrStr(3) translates error conditions into error
       messages.  By convention, the small negative values are assumed  to  be
       negated  versions  of  the Unix error codes as defined in <errno.h> and
       the strings returned are as per  strerror(3C).   The  larger,  negative
       error codes are PMAPI error conditions.

       One  error,  common to all PMAPI routines that interact with pmcd(1) on
       some host is PM_ERR_IPC, which  indicates  the  communication  link  to
       pmcd(1) has been lost.

PCP ENVIRONMENT

       Most  environment variables are described in PCPIntro(1).  In addition,
       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

       PCPIntro(1),    PCPIntro(3),    PMAPI(3),    pmda(3),   pmGetConfig(3),
       pcp.conf(4) and pcp.env(4).