Provided by: pcp_3.5.6ubuntu1_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 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).