Man Linux: Main Page and Category List


       pmns - the performance metrics name space




       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

       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


       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.


       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.


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

       pathname {
               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 or more characters drawn from the alphabetics,
       the  digits  and  the  underscore  ‘‘_’’)  character.   For  alphabetic
       characters   in   a  pathname  component,  upper  and  lower  case  are

       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.

       To support dynamic metrics, where the existence of a metric is known to
       a PMDA, but not visible in the PMNS, a variant syntax for the  pmid  is
       supported,  namely  a domain number followed by asterisks for the other
       components of the pmid, e.g. 14:*:*.   The  corresponding  metric  name
       forms  the  root  of  a  subtree of dynamic metric names defined in the
       corresponding PMDA as identified by the domain number.

       The current allocation of the high-order (PMD or domain)  component  of
       PMIDs is as follows.

            | Range  |                    Allocation                    |
            |      0 | reserved                                         |
            |   1-31 | PMDAs from the PCP base product and/or IRIX      |
            |  32-39 | Oracle                                           |
            |  40-47 | Sybase                                           |
            |  48-55 | Informix                                         |
            |  56-58 | SNMP Gateway PMDA                                |
            |  59-63 | Linux PMDAs                                      |
            |  64-69 | ISV PMDAs                                        |
            | 70-128 | more PMDAs from the PCP base product and/or IRIX |
            |129-510 | End-user PMDAs and demo PMDAs                    |
            |    511 | RESERVED                                         |


       #define IRIX 1
       #define FOO 317
       root {
           dynamic     FOO:*:*

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

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

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

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

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


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