oracular (5) PMNS.5.gz

Provided by: pcp_6.3.0-1_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.

       Loading of a PMNS is done by calling pmLoadNameSpace(3) or pmLoadASCIINameSpace(3).

       As  of  Version  3.10.3  of  PCP,  by  default duplicate names for the same PMID are allowed in the PMNS,
       although pmLoadASCIINameSpace(3) provides an alternative interface with  user-defined  control  over  the
       processing  of  duplicate  names  in the PMNS.  The external 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 is a version 1 archive (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.

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.

       The preprocessing with pmcpp(1) may be omitted in some cases where the PMNS is known to not  contain  any
       C-style    comments,    preprocessor    directives   or   macros.    Refer   to   the   descriptions   of
       pmLoadASCIINameSpace(3) and pmLoadNameSpace(3) for details.

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  is
       drawn  from  the  ASCII(7) character set, beginning with an alphabetic character, and 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-384 │ production PMDAs from PCP packages         │
                                ├────────┼────────────────────────────────────────────┤
                                │385-510 │ end-user PMDAs (allocate from high to low) │
                                ├────────┼────────────────────────────────────────────┤
                                │    511 │ reserved for dynamic PMNS entries          │
                                └────────┴────────────────────────────────────────────┘

EXAMPLE

       #define KERNEL 1
       #define FOO 387
       root {
           network
           cpu
           dynamic     FOO:*:*
       }

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

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

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

       #define USER 20
       #define SYSTEM 21
       #define IDLE 22

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

SEE ALSO

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