Provided by: pcp_2.7.4-20080507_i386 bug

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  formats.   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 associated with a single PMID.  If
       the ASCII format is to  be  used,  duplicate  PMIDs  are  not  allowed,
       although pmLoadASCIINameSpace(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 developers 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), normally 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  environment  variable
       PMNS_DEFAULT.

DISTRIBUTED PMNS

       In PCP version 1, the PMNS functions in the API all operated on a  PMNS
       loaded  locally  from  a  file.  Since  PCP  version  2,  however, PMNS
       functions may get the PMNS information 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 previously 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 pmLoadNameSpace(3) or pmLoadASCIINameSpace(3).  Doing so  will
       load  the  local  PMNS  as specified above. Not calling these functions
       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 directories 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 PMNS  to  this
       non-leaf  node,  with  each  component  in  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 component in the pathname must begin with an alphabetic character,
       and be followed by zero more characters drawn from the alphabetics, the
       digits and the underscore ‘‘_’’) character.  For alphabetic  characters
       in a pathname component, 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, relative to the
       pathname of their parent non-leaf node.  For the descendent nodes, leaf
       nodes have a pmid specification, non-leaf nodes do not.  The syntax for
       the pmid specification has been chosen to help manage the allocation 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 components 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
       root {
           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

       cpp(1),   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).