NAME

       pmns - the performance metrics name space


SYNOPSIS

       $PCP_VAR_DIR/pmns


DESCRIPTION

       When  using  the Performance Metrics Programming Interface
       (PMAPI) of the  Performance  Co-Pilot  (PCP),  performance
       metrics are identified by an external name in a hierarchic
       Performance Metrics Name Space  (PMNS),  and  an  internal
       identifier, the Performance Metric Identifier (PMID).

       A  PMNS  specifies the association between a metric's name
       and its PMID.

       A PMNS is defined on one or more ASCII source files,  that
       may  be  compiled  using  pmnscomp(1)  to produce a binary
       PMNS.  Note that pmnscomp(1) is normally invoked from  the
       $PCP_VAR_DIR/pmns/Rebuild script if necessary when pmcd(1)
       is started.

       Loading of a PMNS is done  by  calling  pmLoadNameSpace(3)
       which  silently  tolerates either the ASCII or binary for­
       mats.  Alternatively, pmLoadASCIINameSpace(3) may be  used
       to load just the ASCII format.

       If the binary format is used, no checking is performed for
       aliasing in which multiple names in the PMNS  are  associ­
       ated  with  a  single  PMID.  If the ASCII format is to be
       used, duplicate PMIDs are not  allowed,  although  pmLoad­
       ASCIINameSpace(3)  provides  an alternative interface with
       user-defined control  over  the  processing  of  duplicate
       PMIDs  in an ASCII format PMNS.  The external ASCII format
       for a PMNS conforms to the syntax and semantics  described
       in the following sections.

       There   is   one   default   PMNS   in   the  files  below
       $PCP_VAR_DIR/pmns, although users and application develop­
       ers  are  free to create and use alternate PMNS's.  For an
       example   of   this,   see    the    PCP    Tutorial    in
       $PCP_DEMOS_DIR/Tutorial.

       Although  an application can call pmLoadNameSpace(3), nor­
       mally this is only done directly for the -n  command  line
       option  where  an  explicit  root  PMNS file is specified.
       Since PCP version 2 uses a distributed PMNS  (see  below),
       an  application can extract PMNS information from a host's
       PMCD or an archive.  If the PMNS source (pmcd or  archive)
       is  version  1  (see PCPIntro(1)), however, then the local
       PMNS will be loaded using the path specified by the  envi­
       ronment variable PMNS_DEFAULT.

       In  PCP version 1, the PMNS functions in the API all oper­
       ated on a PMNS loaded locally from a file. Since PCP  ver­
       sion  2, however, PMNS functions may get the PMNS informa­
       tion remotely from a PMCD or directly from the  meta  data
       of an archive. We call this a distributed PMNS. It has the
       advantage that the PMNS should always match the source  of
       the metrics.  For example, in PCP version 1, if one wanted
       to access a remote PMCD which had an agent installed which
       one didn't have installed locally, then the local PMNS had
       to be updated just for that agent. This is no  longer  the
       case.

       In order to be compatible with version 1 PMCDs and version
       1   archives   (see   PCPIntro(1)),   the    local    PMNS
       (PMNS_DEFAULT)  is automatically loaded as was done previ­
       ously in PCP version 1.

       From an API level, there has been  minimal  changes.   The
       main  change  is  that  if an application wants to use the
       distributed PMNS then  it  should  not  call  pmLoadNameS­
       pace(3)  or  pmLoadASCIINameSpace(3).   Doing so will load
       the local PMNS as specified above. Not calling these func­
       tions  would  previously (in PCP version 1) cause an error
       when trying to access the PMNS but now (in PCP version  2)
       it  will  force  the PMNS functions to look at the metrics
       source for their information.


PROCESSING FRAMEWORK

       The PMNS specification is initially passed through cpp(1).
       This  means  the  following  facilities may be used in the
       specification

       +  C-style comments

       +  #include directives

       +  #define directives and macro substitution

       +  conditional processing via #if ...  #endif, etc.

       When cpp(1) is executed, the ``standard'' include directo­
       ries are the current directory and $PCP_VAR_DIR/pmns.


SYNTAX

       The  general  syntax for a non-leaf node in the PMNS is as
       follows

       pathanme {
            name      [pmid]
            ...
       }

       Where pathname is the full pathname from the root  of  the

       pathname separated by a ``.''.  The root node for the PMNS
       must have the special name ``root'', but the common prefix
       ``root.'' must be omitted from all pathnames.  Each compo­
       nent in the pathname must begin with an alphabetic charac­
       ter, and be followed by zero more  characters  drawn  from
       the  alphabetics,  the  digits  and  the underscore ``_'')
       character.  For alphabetic characters in a pathname compo­
       nent, upper and lower case are distinguished.

       Non-leaf nodes in the PMNS may be defined in any order.

       The descendent nodes are defined by the set of names, rel­
       ative to the pathname of their parent non-leaf node.   For
       the  descendent  nodes,  leaf nodes have a pmid specifica­
       tion, non-leaf nodes do not.   The  syntax  for  the  pmid
       specification  has  been chosen to help manage the alloca­
       tion of PMIDs across disjoint and  autonomous  domains  of
       administration  and implementation.  Each pmid consists of
       3 integer parts, separated by colons, e.g. 14:27:11.  This
       hierarchic  numbering  scheme  is  intended  to mirror the
       implementation hierarchy  of  performance  metric  domain,
       metrics cluster (data structure or operational similarity)
       and individual metric.  In practice, the two leading  com­
       ponents  are likely to be macros in the PMNS specification
       source, and cpp(1) will convert the  macros  to  integers.
       These  macros  for  the initial components of the pmid are
       likely to be defined either in a  standard  include  file,
       e.g.  $PCP_VAR_DIR/pmns/stdpmid,  or in the current source
       file.

       The current allocation of the high-order (PMD  or  domain)
       component of PMIDs is as follows.
                  +--------+-------------------------+
                  | Range  |       Allocation        |
                  +--------+-------------------------+
                  |      0 | reserved                |
                  +--------+-------------------------+
                  |   1-31 | SGI internal            |
                  +--------+-------------------------+
                  |  32-39 | Oracle                  |
                  +--------+-------------------------+
                  |  40-47 | Sybase                  |
                  +--------+-------------------------+
                  |  48-55 | Informix                |
                  +--------+-------------------------+
                  |     60 | Linux                   |
                  +--------+-------------------------+
                  | 56-127 | ISV Performance Metrics |
                  +--------+-------------------------+
                  |128-254 | End-user applications   |
                  +--------+-------------------------+

EXAMPLE

       #define IRIX 1

           network
           cpu
       }

       #define NETWORK 26
       network {
           intrate                       IRIX:NETWORK:1
           packetrate
       }

       network.packetrate {
           in                            IRIX:NETWORK:35
           out                           IRIX:NETWORK:36
       }

       #define CPU 10
       cpu {
           syscallrate                   IRIX:CPU:10
           util
       }

       #define USER 20
       #define KERNEL 21
       #define IDLE 22

       cpu.util {
           user                          IRIX:CPU:USER
           sys                           IRIX:CPU:KERNEL
           idle                          IRIX:CPU:IDLE
       }


SEE ALSO

       PCPIntro(1),  pmcd(1), pmnscomp(1), PCPIntro(3), PMAPI(3),
       pmErrStr(3),   pmGetConfig(3),    pmLoadASCIINameSpace(3),
       pmLoadNameSpace(3), pcp.conf(4) and pcp.env(4).


Man(1) output converted with man2html