Provided by: pcp_3.5.11_amd64 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 pmcpp(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 #ifdef ...  #endif, etc.

       When pmcpp(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

       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 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 pmcpp(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                                         │
                      └────────┴──────────────────────────────────────────────────┘

EXAMPLE

       #define IRIX 1
       #define FOO 317
       root {
           network
           cpu
           dynamic     FOO:*:*
       }

       #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),  pmcpp(1),   pmnscomp(1),   PCPIntro(3),   PMAPI(3),   pmErrStr(3),
       pmGetConfig(3), pmLoadASCIINameSpace(3), pmLoadNameSpace(3), pcp.conf(4) and pcp.env(4).