pmns(5) - f29

1PMNS(5)                       File Formats Manual                      PMNS(5)
2
3
4

NAME

6       pmns - the performance metrics name space
7

SYNOPSIS

9       $PCP_VAR_DIR/pmns
10

DESCRIPTION

12       When using the Performance Metrics Programming Interface (PMAPI) of the
13       Performance Co-Pilot (PCP), performance metrics are  identified  by  an
14       external  name  in  a hierarchic Performance Metrics Name Space (PMNS),
15       and an internal identifier, the Performance Metric Identifier (PMID).
16
17       A PMNS specifies the association between a metric's name and its PMID.
18
19       A PMNS is defined on one or more ASCII source files.
20
21       Loading of a PMNS is done by calling pmLoadNameSpace(3) or  pmLoadASCI‐
22       INameSpace(3).
23
24       As  of  Version  3.10.3 of PCP, by default duplicate names for the same
25       PMID are allowed in the PMNS, although pmLoadASCIINameSpace(3) provides
26       an  alternative interface with user-defined control over the processing
27       of duplicate names in the PMNS.  The external format for  a  PMNS  con‐
28       forms to the syntax and semantics described in the following sections.
29
30       There  is  one  default  PMNS  in  the  files  below $PCP_VAR_DIR/pmns,
31       although users and application developers are free to  create  and  use
32       alternate  PMNS's.   For  an  example  of this, see the PCP Tutorial in
33       $PCP_DEMOS_DIR/Tutorial.
34
35       Although an application can call pmLoadNameSpace(3), normally  this  is
36       only  done  directly  for  the -n command line option where an explicit
37       root PMNS file is specified.  Since PCP version 2  uses  a  distributed
38       PMNS  (see  below),  an application can extract PMNS information from a
39       host's PMCD or an archive.  If the PMNS source is a version  1  archive
40       (see  PCPIntro(1)),  however,  then the local PMNS will be loaded using
41       the path specified by the environment variable PMNS_DEFAULT.
42

DISTRIBUTED PMNS

44       In PCP version 1, the PMNS functions in the API all operated on a  PMNS
45       loaded  locally  from  a file. Since PCP version 2, however, PMNS func‐
46       tions may get the PMNS information remotely from  a  PMCD  or  directly
47       from the meta data of an archive.
48

PROCESSING FRAMEWORK

50       The  PMNS  specification  is  initially  passed through pmcpp(1).  This
51       means the following facilities may be used in the specification
52
53       +  C-style comments
54
55       +  #include directives
56
57       +  #define directives and macro substitution
58
59       +  conditional processing via #ifdef ...  #endif, etc.
60
61       When pmcpp(1) is executed, the ``standard'' include directories are the
62       current directory and $PCP_VAR_DIR/pmns.
63
64       The pre-processing with pmcpp(1) may be omitted in some cases where the
65       PMNS is known to not contain any C-style comments, preprocessor  direc‐
66       tives  or macros.  Refer to the descriptions of pmLoadASCIINameSpace(3)
67       and pmLoadNameSpace(3) for details.
68

SYNTAX

70       The general syntax for a non-leaf node in the PMNS is as follows
71
72       pathname {
73               name      [pmid]
74               ...
75       }
76
77       Where pathname is the full pathname from the root of the PMNS  to  this
78       non-leaf  node,  with  each  component  in  the pathname separated by a
79       ``.''.  The root node for the PMNS must have the special name ``root'',
80       but  the  common  prefix  ``root.'' must be omitted from all pathnames.
81       Each component in the pathname must begin with an alphabetic character,
82       and  be followed by zero or more characters drawn from the alphabetics,
83       the digits and the underscore ``_'') character.  For alphabetic charac‐
84       ters in a pathname component, upper and lower case are distinguished.
85
86       Non-leaf nodes in the PMNS may be defined in any order.
87
88       The  descendent  nodes are defined by the set of names, relative to the
89       pathname of their parent non-leaf node.  For the descendent nodes, leaf
90       nodes have a pmid specification, non-leaf nodes do not.  The syntax for
91       the pmid specification has been chosen to help manage the allocation of
92       PMIDs  across  disjoint  and  autonomous  domains of administration and
93       implementation.  Each pmid consists of 3 integer  parts,  separated  by
94       colons, e.g. 14:27:11.  This hierarchic numbering scheme is intended to
95       mirror the implementation hierarchy of performance metric domain,  met‐
96       rics  cluster (data structure or operational similarity) and individual
97       metric.  In practice, the two  leading  components  are  likely  to  be
98       macros  in the PMNS specification source, and pmcpp(1) will convert the
99       macros to integers.  These macros for the  initial  components  of  the
100       pmid  are  likely to be defined either in a standard include file, e.g.
101       $PCP_VAR_DIR/pmns/stdpmid, or in the current source file.
102
103       To support dynamic metrics, where the existence of a metric is known to
104       a  PMDA,  but not visible in the PMNS, a variant syntax for the pmid is
105       supported, namely a domain number followed by asterisks for  the  other
106       components  of  the  pmid,  e.g. 14:*:*.  The corresponding metric name
107       forms the root of a subtree of dynamic metric names defined in the cor‐
108       responding PMDA as identified by the domain number.
109
110       The  current  allocation of the high-order (PMD or domain) component of
111       PMIDs is as follows.
112
113               ┌────────┬────────────────────────────────────────────┐
114               │ Range  │                 Allocation                 │
115               ├────────┼────────────────────────────────────────────┤
116               │      0 │ reserved                                   │
117               ├────────┼────────────────────────────────────────────┤
118               │  1-384 │ production PMDAs from PCP packages         │
119               ├────────┼────────────────────────────────────────────┤
120               │385-510 │ end-user PMDAs (allocate from high to low) │
121               ├────────┼────────────────────────────────────────────┤
122               │    511 │ reserved for dynamic PMNS entries          │
123               └────────┴────────────────────────────────────────────┘

EXAMPLE

125       #define KERNEL 1
126       #define FOO 387
127       root {
128           network
129           cpu
130           dynamic     FOO:*:*
131       }
132
133       #define NETWORK 26
134       network {
135           intrate     KERNEL:NETWORK:1
136           packetrate
137       }
138
139       network.packetrate {
140           in          KERNEL:NETWORK:35
141           out         KERNEL:NETWORK:36
142       }
143
144       #define CPU 10
145       cpu {
146           syscallrate KERNEL:CPU:10
147           util
148       }
149
150       #define USER 20
151       #define SYSTEM 21
152       #define IDLE 22
153
154       cpu.util {
155           user        KERNEL:CPU:USER
156           sys         KERNEL:CPU:SYSTEM
157           idle        KERNEL:CPU:IDLE
158       }
159