1PCPINTRO(3) Library Functions Manual PCPINTRO(3)
2
6 PCPIntro - introduction to the Performance Co-Pilot (PCP) libraries
7
9 Performance Co-Pilot (PCP) is a toolkit designed for monitoring and
10 managing system-level performance.
11 The PCP libraries support the APIs required to create new performance
13 monitoring tools and new agents (or PMDAs) to export performance data.
14 The libpcp library is used in both cases. The libpcp_pmda library is
15 used only for PMDAs.
16 Individual library routines are documented in their own manual page en‐
18 tries.
19 Most routines return an integer value; greater than equal to zero for
21 success and less than zero for an error. The error codes have symbolic
22 names defined in <pcp/pmapi.h>. Other negative values are used to en‐
23 code errors that can be mapped to the traditional errno values defined
24 in <errno.h>, with the value negated. To translate all PCP error codes
25 into useful messages use either pmerr(1) or pmErrStr(3); the latter may
26 also be used to decode the -errno cases.
27
29 These common errors may occur in various PCP interactions.
30 PM_ERR_TIMEOUT
32 Timeout waiting for a response from PMCD
33 Many interactions between PCP applications involve synchronous mes‐
34 sage passing, and these are subject to timeout constraints. These
35 errors are most frequently encountered when using network connec‐
36 tions with slow data rates or long latencies.
37 For client-pmcd timeouts, refer to PCPIntro(1) for environment
39 variables that may be used to modify the timeout thresholds. For
40 pmcd-PMDA timeouts refer to the -t and -q options of pmcd(1) and
41 the PCP metric pmcd.control.timeout that can be dynamically changed
42 with pmstore(1).
43 PM_ERR_APPVERSION
45 Metric not supported by this version of monitored application
46 Some performance metrics are unavailable from specific versions of
47 the associated PMDA, or may be unavailable because the underlying
48 instrumentation has changed or is not installed or is not enabled.
49 This error is used in results from pmFetch(3) to indicate these
50 situations.
51 PM_ERR_IPC
53 IPC protocol failure
54 Generic protocol failure on a pipe or socket connecting two PCP ap‐
55 plications, eg. client-pmcd, or client-pmtime, or PMDA-pmcd or
56 pmlc-pmlogger.
57 PM_ERR_TEXT
59 One-line or help text is not available
60 Set by a PMDA, and passed back to a PCP client, to indicate that
61 the PMDA is unable to supply the requested metric or instance do‐
62 main help text.
63 PM_ERR_VALUE
65 Missing metric value(s)
66 This error is used for a number of conditions in which the value of
67 a performance metric is inappropriate for the context in which it
68 is being used, eg.
69 (a) Bad value for the metric pmcd.timezone when trying to set the
71 timezone via pmNewContextZone(3) for a remote or archive con‐
72 text.
73 (b) Attempting to interpolate values for a metric with non-numeric
75 data type from a set of PCP archives.
76 (c) A bad result data structure passed to pmStore(3).
78 PM_ERR_NAME
80 Unknown metric name
81 Just what the message says.
82 PM_ERR_PMID
84 Unknown or illegal metric identifier
85 Just what the message says.
86 PM_ERR_INDOM
88 Unknown or illegal instance domain identifier
89 A request nominates an instance domain that is unknown or PM_IN‐
90 DOM_NULL. May occur as a consequence of the instance domain iden‐
91 tifier passed by a PCP client to pmGetInDom(3), pmLookupInDom(3),
92 pmNameInDom(3), pmGetInDomArchive(3), pmLookupInDomArchive(3), pm‐
93 NameInDomArchive(3) or a request passed from pmcd(1) to a PMDA.
94 PM_ERR_EOF
96 IPC channel closed
97 End of file on a pipe or socket connecting two PCP applications,
98 eg. client-pmcd, or client-pmtime or PMDA-pmcd.
99 PM_ERR_NOCONTEXT
101 Attempt to use an illegal context
102 Typically caused by a PCP client that tries to make calls before
103 calling pmNewContext(3) or after calling pmDestroyContext(3).
104 PM_ERR_PERMISSION
106 No permission to perform requested operation
107 PCP-specific access controls apply to pmcd(1) and pmlogger(1).
108 Platform-specific permission errors are returned as -EPERM.
109 PM_ERR_CONV
111 Impossible value or scale conversion
112 Some value conversion requests are illegal, eg. bad debug flag sym‐
113 bolic name for -D/--debug option, or asking pmExtractValue(3) to
114 translate non-numeric data types to numbers and vice versa.
115 PM_ERR_TRUNC
117 Truncation in value conversion
118 Some conversion requests to pmExtractValue(3) cannot be performed
119 based on the metric types and values involved, in this case conver‐
120 sion would result in loss of precision.
121 PM_ERR_SIGN
123 Negative value in conversion to unsigned
124 Some conversion requests to pmExtractValue(3) cannot be performed
125 based on the metric types and values involved, in this case con‐
126 verting a negative value to an unsigned value.
127 PM_ERR_TYPE
129 Unknown or illegal metric type
130 The metric type is held in the metric descriptor and sometimes en‐
131 coded in the metric values returned from a call to pmFetch(3). Le‐
132 gal values for the metric type are defined by the PM_TYPE_* macros
133 in <pcp/pmapi.h>.
134 PM_ERR_UNIT
136 Illegal pmUnits specification
137 Some conversion requests to pmConvScale(3) cannot be performed due
138 to illegal or incompatible specifications of the source and desti‐
139 nation units.
140 PM_ERR_PROFILE
142 Explicit instance identifier(s) required
143 Some PMDAs, especially the proc PMDA, will not return ``all in‐
144 stances'' for a pmFetch(3) request due to the cost. The client
145 must explicitly built an instance profile using pmAddProfile(3)
146 and/or pmDelProfile(3) before calling pmFetch(3). See also the
147 -F/--fetchall option to pminfo(1).
148 PM_ERR_INST
150 Unknown or illegal instance identifier
151 A request to a PMDA nominates an instance that is unknown. May oc‐
152 cur as a consequence of the profile established prior to a pm‐
153 Fetch(3) call, or an explicit instance name or identifier to pm‐
154 LookupInDom(3) or pmNameInDom(3).
155 PM_ERR_MODE
157 Illegal mode specification
158 Illegal mode argument to pmSetMode(3).
159 PM_ERR_PROFILESPEC
161 NULL pmInDom with non-NULL instlist
162 Bad arguments passed from a PCP client to pmAddProfile(3).
163 PM_ERR_TOOSMALL
165 Insufficient elements in list
166 Parameter passing error by caller specifying a list with less than
167 one element to pmFetch(3), pmLookupName(3) or pmStore(3).
168 PM_ERR_FAULT
170 QA fault injected
171 For testing, there is a ``fault injection'' version of libpcp and
172 this error indicates a misuse of the fault injection infrastruc‐
173 ture.
174 PM_ERR_THREAD
176 Operation not supported for multi-threaded applications
177 As documented in PMAPI(3) and elsewhere, some libpcp routines are
178 intended solely for use from single-threaded applications.
179 PM_ERR_NOCONTAINER
181 Container not found The user supplied container name does not match
182 any known container.
183 PM_ERR_BADSTORE
185 Bad input to pmstore
186 The metric value provided for a pmStore(3) operation is in the
187 wrong format, or of the wrong type or has the wrong number of val‐
188 ues.
189 PM_ERR_TOOBIG
191 Result size exceeded
192 Indicates a fatal error in the message (or PDU) passing protocol
193 between two PCP applications. This is an internal error, and other
194 than an exotic networking failure, should not occur.
195 PM_ERR_RESET
197 PMCD reset or configuration change
198 Not used.
199 Refer to pmFetch(3) for an alternative mechanism that may be used
201 to notify a PCP client when pmcd(1) has experienced one or more
202 configuration changes since the last request from the client. Usu‐
203 ally these changes involve a change to the namespace exported via
204 pmcd and/or changes to the PMDAs under pmcd's control.
205 PM_ERR_FAULT
207 QA fault injected
208 Used only for PCP Quality Assurance (QA) testing.
209 PM_ERR_NYI
211 Functionality not yet implemented
212 Self explanatory and rarely used.
213 PM_ERR_GENERIC
215 Generic error, already reported above
216 Rarely used, this error may be returned when the error condition is
217 a consequent of some earlier returned error and a more precise
218 characterization is not possible.
219 PM_ERR_BADDERIVE
221 Derived metric definition failed
222 When registering a derived metric, the metric expression is either
223 syntactically or semantically incorrect.
224 PM_ERR_NOLABELS
226 No support for metric label metadata
227 Operation requires metric labels, but none are available.
228
230 These errors may occur in the interactions between a PCP client and
231 pmcd(1) providing real-time performance data.
232 PM_ERR_NOAGENT
234 No PMCD agent for domain of request
235 A request sent to pmcd(1) requires information from an agent or
236 PMDA that does not exist. Usually this means the namespace be‐
237 ing used by the client application contains metric names from a
238 previously installed PMDA.
239 PM_ERR_CONNLIMIT
241 PMCD connection limit for this host exceeded
242 The client connection limit for pmcd(1) is controlled by the op‐
243 tional access controls in $PCP_PMCDCONF_PATH. By default there
244 is no limit imposed by the PCP code, and this error would not be
245 seen.
246 PM_ERR_AGAIN
248 Try again. Information not currently available
249 Used to notify a PCP client that the PMDA responsible for deliv‐
250 ering the information is temporarily unavailable. See also
251 PM_ERR_PMDANOTREADY.
252 PM_ERR_NOPROFILE
254 Missing profile - protocol botch
255 Internal error in the communication between a client application
256 and pmcd(1) - should not occur.
257 PM_ERR_NEEDCLIENTCERT
259 PMCD requires a client certificate Authentication failure.
260 PM_ERR_PMDAFENCED
262 PMDA is currently fenced and unable to respond to requests
263 A privileged user has decided to isolate a PMDA from pmcd(1) us‐
264 ing a pmStore(1) operation on the pmcd.agent.fenced metric,
265 which means all fetch-level requests to that PMDA are being
266 blocked.
267
269 These errors may occur in the interactions between a PCP client and the
270 library routines that provide historical performance data from PCP ar‐
271 chives created by pmlogger(1).
272 PM_ERR_LOGFILE
274 Missing archive file
275 Each PCP archive consists of multiple physical files as de‐
276 scribed in pmlogger(1). This error occurs when one of the phys‐
277 ical files is missing or cannot be opened for reading.
278 PM_ERR_EOL
280 End of PCP archive
281 An attempt is made to read past the end file of the last volume
282 of a set of PCP archives, or past the end of the time window (as
283 specified with a -T/--finish option) for a set of PCP archives.
284 PM_ERR_NOTHOST
286 Operation requires context with host source of metrics
287 Calls to pmStore(3) require a host context and are not supported
288 for PCP archives.
289 For archives created with versions of PCP prior to 4.0, the pm‐
291 LookupText(3) and pmLookupInDomText(3) calls will return this
292 code for archive PMAPI contexts (help and one-line text was not
293 previously recorded in archives).
294 PM_ERR_LOGREC
296 Corrupted record in a PCP archive
297 PCP archives can become corrupted for a variety of reasons, but
298 the most common is premature termination of pmlogger(1) without
299 flushing its output buffers.
300 PM_ERR_LABEL
302 Illegal label record at start of a PCP archive file
303 Each physical file in a PCP archive should begin with a common
304 label record. This is a special case of PM_ERR_LOGREC errors.
305 PM_ERR_NODATA
307 Empty archive file
308 An empty physical file can never be part of a valid PCP archive
309 (at least the label record should be present). This is a spe‐
310 cial case of PM_ERR_LOGREC errors.
311 PM_ERR_NOTARCHIVE
313 Operation requires context with archive source of metrics
314 A call to one of the archive variant routines, i.e. pm‐
315 FetchArchive(3), pmGetInDomArchive(3), pmLookupInDomArchive(3)
316 or pmNameInDomArchive(3), when the current context is not asso‐
317 ciated with a set of PCP archives.
318 PM_ERR_PMID_LOG
320 Metric not defined in the PCP archive
321 A PCP client has requested information about a metric, and there
322 is no corresponding information in the set of PCP archives.
323 This should not happen for well-behaved PCP clients.
324 PM_ERR_INDOM_LOG
326 Instance domain identifier not defined in the PCP archive
327 A PCP client has requested information about an instance domain
328 for one or more performance metrics, and there is no correspond‐
329 ing information in the set of PCP archives. If the client is
330 using metric descriptors from the set of archives to identify
331 the instance domain, this is less likely to happen.
332 Because instance domains may vary over time, clients may need to
334 use the variant routines pmGetInDomArchive(3) or pmLookupInDo‐
335 mArchive(3) or pmNameInDomArchive(3) to manipulate the union of
336 the instances in an instance domain over the life of an archive.
337 PM_ERR_INST_LOG
339 Instance identifier not defined in the PCP archive
340 A PCP client has requested information about a specific instance
341 of a performance metric, and there is no corresponding informa‐
342 tion in the set of PCP archives. If the client is using in‐
343 stance names from the instance domain in the set of archives
344 (rather than hard-coded instance names) and instance identifiers
345 from the results returned by pmFetch(3) or pmFetchArchive(3)
346 this is less likely to happen.
347 Because instance domains may vary over time, clients may need to
349 use the variant routines pmLookupInDomArchive(3) or pmNameInDo‐
350 mArchive(3) to manipulate the union of the instances in an in‐
351 stance domain over the life of an archive.
352 PM_ERR_LOGOVERLAP
354 Archives overlap in time
355 When using a context associated with a set of archives, the ar‐
356 chives in the set may not overlap in time.
357 PM_ERR_LOGHOST
359 Archives differ by host
360 When using a context associated with a set of archives, the ar‐
361 chives in the set must all have been generated on the same host.
362 PM_ERR_LOGCHANGETYPE
364 The type of a metric differs among archives
365 When using a context associated with a set of archives, the type
366 of each metric must be same in all of the archives.
367 PM_ERR_LOGCHANGESEM
369 The semantics of a metric differs among archives
370 When using a context associated with a set of archives, the se‐
371 mantics of each metric must be same in all of the archives.
372 PM_ERR_LOGCHANGEINDOM
374 The instance domain of a metric differs among archives
375 When using a context associated with a set of archives, the in‐
376 stance domain of each metric must be same in all of the ar‐
377 chives.
378 PM_ERR_LOGCHANGEUNITS
380 The units of a metric differs among archives
381 When using a context associated with a set of archives, the
382 units of each metric must be same in all of the archives.
383
385 These errors may occur in the interactions between a GUI PCP client and
386 the time control services provided by pmtime(1).
387 PM_ERR_ISCONN
389 Already Connected
390 A PCP client application called pmTimeConnect(3) when already
391 connected to a pmtime(1) instance.
392 PM_ERR_NOTCONN
394 Not Connected
395 A PCP client application called one of the time control routines
396 pmTime*[22m(3) when not currently connected to any pmtime(1) in‐
397 stance.
398 PM_ERR_NEEDPORT
400 A non-null port name is required
401 If a shared pmtime(1) instance is being created the port argu‐
402 ment to pmTimeConnect(3) must not be invalid.
403
405 These errors may occur in the processing of PCP namespace operations.
406 A PCP namespace, see PMNS(5), provides the external names and the in‐
407 ternal identifiers for the available performance metrics.
408 PM_ERR_NONLEAF
410 Metric name is not a leaf in PMNS
411 The metric name passed to pmLookupName(3) names a non-terminal
412 path in the namespace, i.e. a group of metrics rather than a
413 single metric.
414 PM_ERR_DUPPMNS
416 Attempt to reload the PMNS
417 When using an explicit local namespace, it is illegal to call
418 either of pmLoadNameSpace(3) or pmLoadASCIINameSpace(3) more
419 than once.
420 PM_ERR_PMNS
422 Problems parsing PMNS definitions
423 Only occurs when an ASCII namespace is explicitly loaded.
424 PM_ERR_NOPMNS
426 PMNS not accessible
427 Only occurs when an ASCII namespace is explicitly loaded.
428
430 These error codes are used in the interactions between pmcd(1) and the
431 PMDAs that provide the performance data.
432 PM_ERR_PMDANOTREADY
434 PMDA is not yet ready to respond to requests
435 Some PMDAs have long initialization or reset times, and will re‐
436 spond to pmcd(1) with this error if they are busy at the moment.
437 This error translates to PM_ERR_AGAIN for the PCP client who
438 made the request to pmcd which caused the initial request to the
439 PMDA. At some later time the PMDA will inform pmcd (see
440 PM_ERR_PMDAREADY) that it is now ready to process requests, and
441 client requests will begin to succeed.
442 PM_ERR_PMDAREADY
444 PMDA is now responsive to requests
445 Used by PMDAs to asynchronously inform pmcd(1) that they are now
446 willing to resume processing requests. See also PM_ERR_PMDAN‐
447 OTREADY.
448
450 Environment variables with the prefix PCP_ are used to parameterize the
451 file and directory names used by PCP. On each installation, the file
452 /etc/pcp.conf contains the local values for these variables. The
453 $PCP_CONF variable may be used to specify an alternative configuration
454 file, as described in pcp.conf(5). Values for these variables may be
455 obtained programmatically using the pmGetConfig(3) function.
456
458 PCPIntro(1), pmcd(1), pmerr(1), pminfo(1), pmtime(1), pmstore(1), pm‐
459 logger(1), PMAPI(3), pmAddProfile(3), pmDelProfile(3), pmConvScale(3),
460 pmNewContext(3), pmDestroyContext(3), pmErrStr(3), pmExtractValue(3),
461 pmFetch(3), pmFetchArchive(3), pmGetConfig(3), pmGetInDom(3),
462 pmGetInDomArchive(3), pmLoadNameSpace(3), pmLookupInDom(3), pmLookupIn‐
463 DomText(3), pmLookupName(3), pmLookupText(3), pmNameInDom(3), pmNameIn‐
464 DomArchive(3), pmSetMode(3), pmStore(3), pmTimeConnect(3), pcp.conf(5),
465 pcp.env(5) and PMNS(5).
466Performance Co-Pilot PCP PCPINTRO(3)