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
18 entries.
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
23 encode errors that can be mapped to the traditional errno values
24 defined in <errno.h>, with the value negated. To translate all PCP
25 error codes into useful messages use either pmerr(1) or pmErrStr(3);
26 the latter may 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
55 applications, eg. client-pmcd, or client-pmtime, or PMDA-pmcd or
56 pmlc-pmlogger.
57 PM_ERR_TEXT
59 Oneline 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
62 domain 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
90 PM_INDOM_NULL. May occur as a consequence of the instance domain
91 identifier passed by a PCP client to pmGetInDom(3), pmLookupIn‐
92 Dom(3), pmNameInDom(3), pmGetInDomArchive(3), pmLookupInDo‐
93 mArchive(3), pmNameInDomArchive(3) or a request passed from pmcd(1)
94 to a PMDA.
95 PM_ERR_EOF
97 IPC channel closed
98 End of file on a pipe or socket connecting two PCP applications,
99 eg. client-pmcd, or client-pmtime or PMDA-pmcd.
100 PM_ERR_NOCONTEXT
102 Attempt to use an illegal context
103 Typically caused by a PCP client that tries to make calls before
104 calling pmNewContext(3) or after calling pmDestroyContext(3).
105 PM_ERR_PERMISSION
107 No permission to perform requested operation
108 PCP-specific access controls apply to pmcd(1) and pmlogger(1).
109 Platform-specific permission errors are returned as -EPERM.
110 PM_ERR_CONV
112 Impossible value or scale conversion
113 Some value conversion requests are illegal, eg. bad debug flag sym‐
114 bolic name for -D/--debug option, or asking pmExtractValue(3) to
115 translate non-numeric data types to numbers and vice versa.
116 PM_ERR_TRUNC
118 Truncation in value conversion
119 Some conversion requests to pmExtractValue(3) cannot be performed
120 based on the metric types and values involved, in this case conver‐
121 sion would result in loss of precision.
122 PM_ERR_SIGN
124 Negative value in conversion to unsigned
125 Some conversion requests to pmExtractValue(3) cannot be performed
126 based on the metric types and values involved, in this case con‐
127 verting a negative value to an unsigned value.
128 PM_ERR_TYPE
130 Unknown or illegal metric type
131 The metric type is held in the metric descriptor and sometimes
132 encoded in the metric values returned from a call to pmFetch(3).
133 Legal values for the metric type are defined by the PM_TYPE_*
134 macros in <pcp/pmapi.h>.
135 PM_ERR_UNIT
137 Illegal pmUnits specification
138 Some conversion requests to pmConvScale(3) cannot be performed due
139 to illegal or incompatible specifications of the source and desti‐
140 nation units.
141 PM_ERR_PROFILE
143 Explicit instance identifier(s) required
144 Some PMDAs, especially the proc PMDA, will not return ``all
145 instances'' for a pmFetch(3) request due to the cost. The client
146 must explicitly built an instance profile using pmAddProfile(3)
147 and/or pmDelProfile(3) before calling pmFetch(3). See also the
148 -F/--fetchall option to pminfo(1).
149 PM_ERR_INST
151 Unknown or illegal instance identifier
152 A request to a PMDA nominates an instance that is unknown. May
153 occur as a consequence of the profile established prior to a
154 pmFetch(3) call, or an explicit instance name or identifier to
155 pmLookupInDom(3) or pmNameInDom(3).
156 PM_ERR_MODE
158 Illegal mode specification
159 Illegal mode argument to pmSetMode(3).
160 PM_ERR_PROFILESPEC
162 NULL pmInDom with non-NULL instlist
163 Bad arguments passed from a PCP client to pmAddProfile(3).
164 PM_ERR_TOOSMALL
166 Insufficient elements in list
167 Parameter passing error by caller specifying a list with less than
168 one element to pmFetch(3), pmLookupName(3) or pmStore(3).
169 PM_ERR_FAULT
171 QA fault injected
172 For testing, there is a ``fault injection'' version of libpcp and
173 this error indicates a misuse of the fault injection infrastruc‐
174 ture.
175 PM_ERR_THREAD
177 Operation not supported for multi-threaded applications
178 As documented in PMAPI(3) and elsewhere, some libpcp routines are
179 intended solely for use from single-threaded applications.
180 PM_ERR_NOCONTAINER
182 Container not found The user supplied container name does not match
183 any known container.
184 PM_ERR_BADSTORE
186 Bad input to pmstore
187 The metric value provided for a pmStore(3) operation is in the
188 wrong format, or of the wrong type or has the wrong number of val‐
189 ues.
190 PM_ERR_TOOBIG
192 Result size exceeded
193 Indicates a fatal error in the message (or PDU) passing protocol
194 between two PCP applications. This is an internal error, and other
195 than an exotic networking failure, should not occur.
196 PM_ERR_RESET
198 PMCD reset or configuration change
199 Not used.
200 Refer to pmFetch(3) for an alternative mechanism that may be used
202 to notify a PCP client when pmcd(1) has experienced one or more
203 configuration changes since the last request from the client. Usu‐
204 ally these changes involve a change to the namespace exported via
205 pmcd and/or changes to the PMDAs under pmcd's control.
206 PM_ERR_FAULT
208 QA fault injected
209 Used only for PCP Quality Assurance (QA) testing.
210 PM_ERR_NYI
212 Functionality not yet implemented
213 Self explanatory and rarely used.
214 PM_ERR_GENERIC
216 Generic error, already reported above
217 Rarely used, this error may be returned when the error condition is
218 a consequent of some earlier returned error and a more precise
219 characterization is not possible.
220 PM_ERR_BADDERIVE
222 Derived metric definition failed
223 When registering a derived metric, the metric expression is either
224 syntactically or semantically incorrect.
225 PM_ERR_NOLABELS
227 No support for metric label metadata
228 Operation requires metric labels, but none are available.
229
231 These errors may occur in the interactions between a PCP client and
232 pmcd(1) providing real-time performance data.
233 PM_ERR_NOAGENT
235 No PMCD agent for domain of request
236 A request sent to pmcd(1) requires information from an agent or
237 PMDA that does not exist. Usually this means the namespace
238 being used by the client application contains metric names from
239 a previously installed PMDA.
240 PM_ERR_CONNLIMIT
242 PMCD connection limit for this host exceeded
243 The client connection limit for pmcd(1) is controlled by the
244 optional access controls in $PCP_PMCDCONF_PATH. By default
245 there is no limit imposed by the PCP code, and this error would
246 not be seen.
247 PM_ERR_AGAIN
249 Try again. Information not currently available
250 Used to notify a PCP client that the PMDA responsible for deliv‐
251 ering the information is temporarily unavailable. See also
252 PM_ERR_PMDANOTREADY.
253 PM_ERR_NOPROFILE
255 Missing profile - protocol botch
256 Internal error in the communication between a client application
257 and pmcd(1) - should not occur.
258 PM_ERR_NEEDCLIENTCERT
260 PMCD requires a client certificate Authentication failure.
261 PM_ERR_PMDAFENCED
263 PMDA is currently fenced and unable to respond to requests
264 A privileged user has decided to isolate a PMDA from pmcd(1)
265 using a pmStore(1) operation on the pmcd.agent.fenced metric,
266 which means all fetch-level requests to that PMDA are being
267 blocked.
268
270 These errors may occur in the interactions between a PCP client and the
271 library routines that provide historical performance data from PCP ar‐
272 chives created by pmlogger(1).
273 PM_ERR_LOGFILE
275 Missing archive file
276 Each PCP archive consists of multiple physical files as
277 described in pmlogger(1). This error occurs when one of the
278 physical files is missing or cannot be opened for reading.
279 PM_ERR_EOL
281 End of PCP archive log
282 An attempt is made to read past the end file of the last volume
283 of a set of PCP archives, or past the end of the time window (as
284 specified with a -T/--finish option) for a set of PCP archives.
285 PM_ERR_NOTHOST
287 Operation requires context with host source of metrics
288 Calls to pmStore(3) require a host context and are not supported
289 for PCP archives.
290 For archives created with versions of PCP prior to 4.0, the
292 pmLookupText(3) and pmLookupInDomText(3) calls will return this
293 code for archive PMAPI contexts (help and one-line text was not
294 previously recorded in archive logs).
295 PM_ERR_LOGREC
297 Corrupted record in a PCP archive log
298 PCP archives can become corrupted for a variety of reasons, but
299 the most common is premature termination of pmlogger(1) without
300 flushing its output buffers.
301 PM_ERR_LABEL
303 Illegal label record at start of a PCP archive log file
304 Each physical file in a PCP archive should begin with a common
305 label record. This is a special case of PM_ERR_LOGREC errors.
306 PM_ERR_NODATA
308 Empty archive log file
309 An empty physical file can never be part of a valid PCP archive
310 (at least the label record should be present). This is a spe‐
311 cial case of PM_ERR_LOGREC errors.
312 PM_ERR_NOTARCHIVE
314 Operation requires context with archive source of metrics
315 A call to one of the archive variant routines, i.e.
316 pmFetchArchive(3), pmGetInDomArchive(3), pmLookupInDomArchive(3)
317 or pmNameInDomArchive(3), when the current context is not asso‐
318 ciated with a set of PCP archives.
319 PM_ERR_PMID_LOG
321 Metric not defined in the PCP archive log
322 A PCP client has requested information about a metric, and there
323 is no corresponding information in the set of PCP archives.
324 This should not happen for well-behaved PCP clients.
325 PM_ERR_INDOM_LOG
327 Instance domain identifier not defined in the PCP archive log
328 A PCP client has requested information about an instance domain
329 for one or more performance metrics, and there is no correspond‐
330 ing information in the set of PCP archives. If the client is
331 using metric descriptors from the set of archives to identify
332 the instance domain, this is less likely to happen.
333 Because instance domains may vary over time, clients may need to
335 use the variant routines pmGetInDomArchive(3) or pmLookupInDo‐
336 mArchive(3) or pmNameInDomArchive(3) to manipulate the union of
337 the instances in an instance domain over the life of an archive.
338 PM_ERR_INST_LOG
340 Instance identifier not defined in the PCP archive log
341 A PCP client has requested information about a specific instance
342 of a performance metric, and there is no corresponding informa‐
343 tion in the set of PCP archives. If the client is using
344 instance names from the instance domain in the set of archives
345 (rather than hard-coded instance names) and instance identifiers
346 from the results returned by pmFetch(3) or pmFetchArchive(3)
347 this is less likely to happen.
348 Because instance domains may vary over time, clients may need to
350 use the variant routines pmLookupInDomArchive(3) or pmNameInDo‐
351 mArchive(3) to manipulate the union of the instances in an
352 instance domain over the life of an archive.
353 PM_ERR_LOGOVERLAP
355 Archives overlap in time
356 When using a context associated with a set of archives, the ar‐
357 chives in the set may not overlap in time.
358 PM_ERR_LOGHOST
360 Archives differ by host
361 When using a context associated with a set of archives, the ar‐
362 chives in the set must all have been generated on the same host.
363 PM_ERR_LOGCHANGETYPE
365 The type of a metric differs among archives
366 When using a context associated with a set of archives, the type
367 of each metric must be same in all of the archives.
368 PM_ERR_LOGCHANGESEM
370 The semantics of a metric differs among archives
371 When using a context associated with a set of archives, the
372 semantics of each metric must be same in all of the archives.
373 PM_ERR_LOGCHANGEINDOM
375 The instance domain of a metric differs among archives
376 When using a context associated with a set of archives, the
377 instance domain of each metric must be same in all of the ar‐
378 chives.
379 PM_ERR_LOGCHANGEUNITS
381 The units of a metric differs among archives
382 When using a context associated with a set of archives, the
383 units of each metric must be same in all of the archives.
384
386 These errors may occur in the interactions between a GUI PCP client and
387 the time control services provided by pmtime(1).
388 PM_ERR_ISCONN
390 Already Connected
391 A PCP client application called pmTimeConnect(3) when already
392 connected to a pmtime(1) instance.
393 PM_ERR_NOTCONN
395 Not Connected
396 A PCP client application called one of the time control routines
397 pmTime*[22m(3) when not currently connected to any pmtime(1)
398 instance.
399 PM_ERR_NEEDPORT
401 A non-null port name is required
402 If a shared pmtime(1) instance is being created the port argu‐
403 ment to pmTimeConnect(3) must not be invalid.
404
406 These errors may occur in the processing of PCP namespace operations.
407 A PCP namespace, see PMNS(5), provides the external names and the
408 internal identifiers for the available performance metrics.
409 PM_ERR_NONLEAF
411 Metric name is not a leaf in PMNS
412 The metric name passed to pmLookupName(3) names a non-terminal
413 path in the namespace, i.e. a group of metrics rather than a
414 single metric.
415 PM_ERR_DUPPMNS
417 Attempt to reload the PMNS
418 When using an explicit local namespace, it is illegal to call
419 either of pmLoadNameSpace(3) or pmLoadASCIINameSpace(3) more
420 than once.
421 PM_ERR_PMNS
423 Problems parsing PMNS definitions
424 Only occurs when an ASCII namespace is explicitly loaded.
425 PM_ERR_NOPMNS
427 PMNS not accessible
428 Only occurs when an ASCII namespace is explicitly loaded.
429
431 These error codes are used in the interactions between pmcd(1) and the
432 PMDAs that provide the performance data.
433 PM_ERR_PMDANOTREADY
435 PMDA is not yet ready to respond to requests
436 Some PMDAs have long initialization or reset times, and will
437 respond to pmcd(1) with this error if they are busy at the
438 moment. This error translates to PM_ERR_AGAIN for the PCP
439 client who made the request to pmcd which caused the initial
440 request to the PMDA. At some later time the PMDA will inform
441 pmcd (see PM_ERR_PMDAREADY) that it is now ready to process
442 requests, and client requests will begin to succeed.
443 PM_ERR_PMDAREADY
445 PMDA is now responsive to requests
446 Used by PMDAs to asynchronously inform pmcd(1) that they are now
447 willing to resume processing requests. See also PM_ERR_PMDAN‐
448 OTREADY.
449
451 Environment variables with the prefix PCP_ are used to parameterize the
452 file and directory names used by PCP. On each installation, the file
453 /etc/pcp.conf contains the local values for these variables. The
454 $PCP_CONF variable may be used to specify an alternative configuration
455 file, as described in pcp.conf(5). Values for these variables may be
456 obtained programmatically using the pmGetConfig(3) function.
457
459 PCPIntro(1), pmcd(1), pmerr(1), pminfo(1), pmtime(1), pmstore(1),
460 pmlogger(1), PMAPI(3), pmAddProfile(3), pmDelProfile(3), pmConvS‐
461 cale(3), pmNewContext(3), pmDestroyContext(3), pmErrStr(3), pmExtract‐
462 Value(3), pmFetch(3), pmFetchArchive(3), pmGetConfig(3), pmGetInDom(3),
463 pmGetInDomArchive(3), pmLoadNameSpace(3), pmLookupInDom(3), pmLookupIn‐
464 DomText(3), pmLookupName(3), pmLookupText(3), pmNameInDom(3), pmNameIn‐
465 DomArchive(3), pmSetMode(3), pmStore(3), pmTimeConnect(3), pcp.conf(5),
466 pcp.env(5) and PMNS(5).
467Performance Co-Pilot PCP PCPINTRO(3)