Ubuntu Manpage: PMNS - the performance metrics name space

name
synopsis
description
distributed pmns
processing framework
syntax
example
see also

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
       }