1PMAPI(3) Library Functions Manual PMAPI(3)
2
6 PMAPI - introduction to the Performance Metrics Application Programming
7 Interface
8
10 #include <pcp/pmapi.h>
11 ... assorted routines ...
13 cc ... -lpcp
15
17 Within the framework of the Performance Co-Pilot (PCP), client applica‐
18 tions are developed using the Performance Metrics Application Program‐
19 ming Interface (PMAPI) that defines a procedural interface with ser‐
20 vices suited to the development of applications with a particular
21 interest in performance metrics.
22 This description presents an overview of the PMAPI and the context in
24 which PMAPI applications are run. The PMAPI is more fully described in
25 the Performance Co-Pilot Programmer's Guide, and the manual pages for
26 the individual PMAPI routines.
27
29 For a description of the Performance Metrics Name Space (PMNS) and
30 associated terms and concepts, see PCPIntro(1).
31 Not all PMIDs need be represented in the PMNS of every application.
33 For example, an application which monitors disk traffic will likely use
34 a name space which references only the PMIDs for I/O statistics.
35 Applications which use the PMAPI may have independent versions of a
37 PMNS, constructed from an initialization file when the application
38 starts; see pmLoadASCIINameSpace(3), pmLoadNameSpace(3), pmnscomp(1)
39 and pmns(4).
40 Internally (below the PMAPI) the implementation of the Performance Met‐
42 rics Collection System (PMCS) uses only the PMIDs, and a PMNS provides
43 an external mapping from a hierarchic taxonomy of names to PMIDs that
44 is convenient in the context of a particular system or particular use
45 of the PMAPI. For the applications programmer, the routines pmLookup‐
46 Name(3) and pmNameID(3) translate between names in a PMNS and PMIDs,
47 and vice versa. The PMNS may be traversed using pmGetChildren(3).
48
50 An application using the PMAPI may manipulate several concurrent con‐
51 texts, each associated with a source of performance metrics, e.g.
52 pmcd(1) on some host, or an archive log of performance metrics as cre‐
53 ated by pmlogger(1).
54 Contexts are identified by a ``handle'', a small integer value that is
56 returned when the context is created; see pmNewContext(3) and pmDupCon‐
57 text(3). Some PMAPI functions require an explicit ``handle'' to iden‐
58 tify the correct context, but more commonly the PMAPI function is exe‐
59 cuted in the ``current'' context. The current context may be discov‐
60 ered using pmWhichContext(3) and changed using pmUseContext(3).
61 If a PMAPI context has not been explicitly established (or the previous
63 current context has been closed using pmDestroyContext(3)) then the
64 current PMAPI context is undefined.
65 In addition to the source of the performance metrics, the context also
67 includes the instance profile and collection time (both described
68 below) which controls how much information is returned, and when the
69 information was collected.
70
72 When performance metric values are returned across the PMAPI to a
73 requesting application, there may be more than one value for a particu‐
74 lar metric. Multiple values, or instances, for a single metric are
75 typically the result of instrumentation being implemented for each
76 instance of a set of similar components or services in a system, e.g.
77 independent counts for each CPU, or each process, or each disk, or each
78 system call type, etc. This multiplicity of values is not enumerated
79 in the name space but rather, when performance metrics are delivered
80 across the PMAPI by pmFetch(3), the format of the result accommodates
81 values for one or more instances, with an instance-value pair encoding
82 the metric value for a particular instance.
83 The instances are identified by an internal identifier assigned by the
85 agent responsible for instantiating the values for the associated per‐
86 formance metric. Each instance identifier has a corresponding external
87 instance identifier name (an ASCII string). The routines
88 pmGetInDom(3), pmLookupInDom(3) and pmNameInDom(3) may be used to enu‐
89 merate all instance identifiers, and to translate between internal and
90 external instance identifiers.
91 All of the instance identifiers for a particular performance metric are
93 collectively known as an instance domain. Multiple performance metrics
94 may share the same instance domain.
95 If only one instance is ever available for a particular performance
97 metric, the instance identifier in the result from pmFetch(3) assumes
98 the special value PM_IN_NULL and may be ignored by the application, and
99 only one instance-value pair appears in the result for that metric.
100 Under these circumstances, the associated instance domain (as returned
101 via pmLookupDesc(3)) is set to PM_INDOM_NULL to indicate that values
102 for this metric are singular.
103 The difficult issue of transient performance metrics (e.g. per-filesys‐
105 tem information, hot-plug replaceable hardware modules, etc.) means
106 that repeated requests for the same PMID may return different numbers
107 of values, and/or some changes in the particular instance identifiers
108 returned. This means applications need to be aware that metric instan‐
109 tiation is guaranteed to be valid at the time of collection only. Sim‐
110 ilar rules apply to the transient semantics of the associated metric
111 values. In general however, it is expected that the bulk of the per‐
112 formance metrics will have instantiation semantics that are fixed over
113 the execution life-time of any PMAPI client.
114
116 The PMAPI supports a wide range of format and type encodings for the
117 values of performance metrics, namely signed and unsigned integers,
118 floating point numbers, 32-bit and 64-bit encodings of all of the
119 above, ASCII strings (C-style, NULL byte terminated), and arbitrary
120 aggregates of binary data.
121 The type field in the pmDesc structure returned by pmLookupDesc(3)
123 identifies the format and type of the values for a particular perfor‐
124 mance metric within a particular PMAPI context.
125 Note that the encoding of values for a particular performance metric
127 may be different for different PMAPI contexts, due to differences in
128 the underlying implementation for different contexts. However it is
129 expected that the vast majority of performance metrics will have con‐
130 sistent value encoding across all versions of all implementations, and
131 hence across all PMAPI contexts.
132 The PMAPI supports routines to automate the handling of the various
134 value formats and types, particularly for the common case where conver‐
135 sion to a canonical format is desired, see pmExtractValue(3) and
136 pmPrintValue(3).
137
139 Independent of how the value is encoded, the value for a performance
140 metric is assumed to be drawn from a set of values that can be
141 described in terms of their dimensionality and scale by a compact
142 encoding as follows. The dimensionality is defined by a power, or
143 index, in each of 3 orthogonal dimensions, namely Space, Time and Count
144 (or Events, which are dimensionless). For example I/O throughput might
145 be represented as Space/Time, while the running total of system calls
146 is Count, memory allocation is Space and average service time is
147 Time/Count. In each dimension there are a number of common scale val‐
148 ues that may be used to better encode ranges that might otherwise
149 exhaust the precision of a 32-bit value. This information is encoded
150 in the pmUnits structure which is embedded in the pmDesc structure
151 returned from pmLookupDesc(3).
152 The routine pmConvScale(3) is provided to convert values in conjunction
154 with the pmUnits structures that defines the dimensionality and scale
155 of the values for a particular performance metric as returned from
156 pmFetch(3), and the desired dimensionality and scale of the value the
157 PMAPI client wishes to manipulate.
158
160 The set of instances for performance metrics returned from a pmFetch(3)
161 call may be filtered or restricted using an instance profile. There is
162 one instance profile for each PMAPI context the application creates,
163 and each instance profile may include instances from one or more
164 instance domains.
165 The routines pmAddProfile(3) and pmDelProfile(3) may be used to dynami‐
167 cally adjust the instance profile.
168
170 For each set of values for performance metrics returned via pmFetch(3)
171 there is an associated ``timestamp'' that serves to identify when the
172 performance metric values were collected; for metrics being delivered
173 from a real-time source (i.e. pmcd(1) on some host) this would typi‐
174 cally be not long before they were exported across the PMAPI, and for
175 metrics being delivered from an archive log, this would be the time
176 when the metrics were written into the archive log.
177 There is an issue here of exactly when individual metrics may have been
179 collected, especially given their origin in potentially different Per‐
180 formance Metric Domains, and variability in the metric updating fre‐
181 quency at the lowest level of the Performance Metric Domain. The PMCS
182 opts for the pragmatic approach, in which the PMAPI implementation
183 undertakes to return all of the metrics with values accurate as of the
184 timestamp, to the best of our ability. The belief is that the inaccu‐
185 racy this introduces is small, and the additional burden of accurate
186 individual timestamping for each returned metric value is neither war‐
187 ranted nor practical (from an implementation viewpoint).
188 Of course, in the case of collection of metrics from multiple hosts the
190 PMAPI client must assume the sanity of the timestamps is constrained by
191 the extent to which clock synchronization protocols are implemented
192 across the network.
193 A PMAPI application may call pmSetMode(3) to vary the requested collec‐
195 tion time, e.g. to rescan performance metrics values from the recent
196 past, or to ``fast-forward'' through an archive log.
197
199 Across the PMAPI, all arguments and results involving a ``list of some‐
200 thing'' are declared to be arrays with an associated argument or func‐
201 tion value to identify the number of elements in the list. This has
202 been done to avoid both the varargs(3) approach and sentinel-terminated
203 lists.
204 Where the size of a result is known at the time of a call, it is the
206 caller's responsibility to allocate (and possibly free) the storage,
207 and the called function will assume the result argument is of an appro‐
208 priate size. Where a result is of variable size and that size cannot
209 be known in advance (e.g. for pmGetChildren(3), pmGetInDom(3),
210 pmNameInDom(3), pmNameID(3), pmLookupText(3) and pmFetch(3)) the PMAPI
211 implementation uses a range of dynamic allocation schemes in the called
212 routine, with the caller responsible for subsequently releasing the
213 storage when no longer required. In some cases this simply involves
214 calls to free(3C), but in others (most notably for the result from
215 pmFetch(3)), special routines (e.g. pmFreeResult(3)) should be used to
216 release the storage.
217 As a general rule, if the called routine returns an error status then
219 no allocation will have been done, and any pointer to a variable sized
220 result is undefined.
221
223 Where error conditions may arise, the functions that comprise the PMAPI
224 conform to a single, simple error notification scheme, as follows;
225 + the function returns an integer
227 + values >= 0 indicate no error, and perhaps some positive status,
229 e.g. the number of things really processed
230 + values < 0 indicate an error, with a global table of error condi‐
232 tions and error messages
233 The PMAPI routine pmErrStr(3) translates error conditions into error
235 messages. By convention, the small negative values are assumed to be
236 negated versions of the Unix error codes as defined in <errno.h> and
237 the strings returned are as per strerror(3C). The larger, negative
238 error codes are PMAPI error conditions.
239 One error, common to all PMAPI routines that interact with pmcd(1) on
241 some host is PM_ERR_IPC, which indicates the communication link to
242 pmcd(1) has been lost.
243
245 Most environment variables are described in PCPIntro(1). In addition,
246 environment variables with the prefix PCP_ are used to parameterize the
247 file and directory names used by PCP. On each installation, the file
248 /etc/pcp.conf contains the local values for these variables. The
249 $PCP_CONF variable may be used to specify an alternative configuration
250 file, as described in pcp.conf(4). Values for these variables may be
251 obtained programatically using the pmGetConfig(3) function.
252
254 PCPIntro(1), PCPIntro(3), PMAPI(3), pmda(3), pmGetConfig(3),
255 pcp.conf(4) and pcp.env(4).
256Performance Co-Pilot SGI PMAPI(3)