1PMNS(4) Kernel Interfaces Manual PMNS(4)
2
6 pmns - the performance metrics name space
7
9 $PCP_VAR_DIR/pmns
10
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 A PMNS specifies the association between a metric's name and its PMID.
18 A PMNS is defined on one or more ASCII source files, that may be com‐
20 piled using pmnscomp(1) to produce a binary PMNS. Note that pmn‐
21 scomp(1) is normally invoked from the $PCP_VAR_DIR/pmns/Rebuild script
22 if necessary when pmcd(1) is started.
23 Loading of a PMNS is done by calling pmLoadNameSpace(3) which silently
25 tolerates either the ASCII or binary formats. Alternatively, pmLoad‐
26 ASCIINameSpace(3) may be used to load just the ASCII format.
27 If the binary format is used, no checking is performed for aliasing in
29 which multiple names in the PMNS are associated with a single PMID. If
30 the ASCII format is to be used, duplicate PMIDs are not allowed,
31 although pmLoadASCIINameSpace(3) provides an alternative interface with
32 user-defined control over the processing of duplicate PMIDs in an ASCII
33 format PMNS. The external ASCII format for a PMNS conforms to the syn‐
34 tax and semantics described in the following sections.
35 There is one default PMNS in the files below $PCP_VAR_DIR/pmns,
37 although users and application developers are free to create and use
38 alternate PMNS's. For an example of this, see the PCP Tutorial in
39 $PCP_DEMOS_DIR/Tutorial.
40 Although an application can call pmLoadNameSpace(3), normally this is
42 only done directly for the -n command line option where an explicit
43 root PMNS file is specified. Since PCP version 2 uses a distributed
44 PMNS (see below), an application can extract PMNS information from a
45 host's PMCD or an archive. If the PMNS source (pmcd or archive) is
46 version 1 (see PCPIntro(1)), however, then the local PMNS will be
47 loaded using the path specified by the environment variable
48 PMNS_DEFAULT.
49
51 In PCP version 1, the PMNS functions in the API all operated on a PMNS
52 loaded locally from a file. Since PCP version 2, however, PMNS func‐
53 tions may get the PMNS information remotely from a PMCD or directly
54 from the meta data of an archive. We call this a distributed PMNS. It
55 has the advantage that the PMNS should always match the source of the
56 metrics. For example, in PCP version 1, if one wanted to access a
57 remote PMCD which had an agent installed which one didn't have
58 installed locally, then the local PMNS had to be updated just for that
59 agent. This is no longer the case.
60 In order to be compatible with version 1 PMCDs and version 1 archives
62 (see PCPIntro(1)), the local PMNS (PMNS_DEFAULT) is automatically
63 loaded as was done previously in PCP version 1.
64 From an API level, there has been minimal changes. The main change is
66 that if an application wants to use the distributed PMNS then it should
67 not call pmLoadNameSpace(3) or pmLoadASCIINameSpace(3). Doing so will
68 load the local PMNS as specified above. Not calling these functions
69 would previously (in PCP version 1) cause an error when trying to
70 access the PMNS but now (in PCP version 2) it will force the PMNS func‐
71 tions to look at the metrics source for their information.
72
74 The PMNS specification is initially passed through cpp(1). This means
75 the following facilities may be used in the specification
76 + C-style comments
78 + #include directives
80 + #define directives and macro substitution
82 + conditional processing via #if ... #endif, etc.
84 When cpp(1) is executed, the ``standard'' include directories are the
86 current directory and $PCP_VAR_DIR/pmns.
87
89 The general syntax for a non-leaf node in the PMNS is as follows
90 pathname {
92 name [pmid]
93 ...
94 }
95 Where pathname is the full pathname from the root of the PMNS to this
97 non-leaf node, with each component in the pathname separated by a
98 ``.''. The root node for the PMNS must have the special name ``root'',
99 but the common prefix ``root.'' must be omitted from all pathnames.
100 Each component in the pathname must begin with an alphabetic character,
101 and be followed by zero or more characters drawn from the alphabetics,
102 the digits and the underscore ``_'') character. For alphabetic charac‐
103 ters in a pathname component, upper and lower case are distinguished.
104 Non-leaf nodes in the PMNS may be defined in any order.
106 The descendent nodes are defined by the set of names, relative to the
108 pathname of their parent non-leaf node. For the descendent nodes, leaf
109 nodes have a pmid specification, non-leaf nodes do not. The syntax for
110 the pmid specification has been chosen to help manage the allocation of
111 PMIDs across disjoint and autonomous domains of administration and
112 implementation. Each pmid consists of 3 integer parts, separated by
113 colons, e.g. 14:27:11. This hierarchic numbering scheme is intended to
114 mirror the implementation hierarchy of performance metric domain, met‐
115 rics cluster (data structure or operational similarity) and individual
116 metric. In practice, the two leading components are likely to be
117 macros in the PMNS specification source, and cpp(1) will convert the
118 macros to integers. These macros for the initial components of the
119 pmid are likely to be defined either in a standard include file, e.g.
120 $PCP_VAR_DIR/pmns/stdpmid, or in the current source file.
121 To support dynamic metrics, where the existence of a metric is known to
123 a PMDA, but not visible in the PMNS, a variant syntax for the pmid is
124 supported, namely a domain number followed by asterisks for the other
125 components of the pmid, e.g. 14:*:*. The corresponding metric name
126 forms the root of a subtree of dynamic metric names defined in the cor‐
127 responding PMDA as identified by the domain number.
128 The current allocation of the high-order (PMD or domain) component of
130 PMIDs is as follows.
131 ┌────────┬──────────────────────────────────────────────────┐
133 │ Range │ Allocation │
134 ├────────┼──────────────────────────────────────────────────┤
135 │ 0 │ reserved │
136 ├────────┼──────────────────────────────────────────────────┤
137 │ 1-31 │ PMDAs from the PCP base product and/or IRIX │
138 ├────────┼──────────────────────────────────────────────────┤
139 │ 32-39 │ Oracle │
140 ├────────┼──────────────────────────────────────────────────┤
141 │ 40-47 │ Sybase │
142 ├────────┼──────────────────────────────────────────────────┤
143 │ 48-55 │ Informix │
144 ├────────┼──────────────────────────────────────────────────┤
145 │ 56-58 │ SNMP Gateway PMDA │
146 ├────────┼──────────────────────────────────────────────────┤
147 │ 59-63 │ Linux PMDAs │
148 ├────────┼──────────────────────────────────────────────────┤
149 │ 64-69 │ ISV PMDAs │
150 ├────────┼──────────────────────────────────────────────────┤
151 │ 70-128 │ more PMDAs from the PCP base product and/or IRIX │
152 ├────────┼──────────────────────────────────────────────────┤
153 │129-510 │ End-user PMDAs and demo PMDAs │
154 ├────────┼──────────────────────────────────────────────────┤
155 │ 511 │ RESERVED │
156 └────────┴──────────────────────────────────────────────────┘
158 #define IRIX 1
159 #define FOO 317
160 root {
161 network
162 cpu
163 dynamic FOO:*:*
164 }
165 #define NETWORK 26
167 network {
168 intrate IRIX:NETWORK:1
169 packetrate
170 }
171 network.packetrate {
173 in IRIX:NETWORK:35
174 out IRIX:NETWORK:36
175 }
176 #define CPU 10
178 cpu {
179 syscallrate IRIX:CPU:10
180 util
181 }
182 #define USER 20
184 #define KERNEL 21
185 #define IDLE 22
186 cpu.util {
188 user IRIX:CPU:USER
189 sys IRIX:CPU:KERNEL
190 idle IRIX:CPU:IDLE
191 }
192
194 cpp(1), PCPIntro(1), pmcd(1), pmnscomp(1), PCPIntro(3), PMAPI(3),
195 pmErrStr(3), pmGetConfig(3), pmLoadASCIINameSpace(3), pmLoadNameS‐
196 pace(3), pcp.conf(4) and pcp.env(4).
197Performance Co-Pilot SGI PMNS(4)