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_THREAD
171 Operation not supported for multi-threaded applications
172 As documented in PMAPI(3) and elsewhere, some libpcp routines are
173 intended solely for use from single-threaded applications.
174 PM_ERR_TOOBIG
176 Result size exceeded
177 Indicates a fatal error in the message (or PDU) passing protocol
178 between two PCP applications. This is an internal error, and other
179 than an exotic networking failure, should not occur.
180 PM_ERR_RESET
182 PMCD reset or configuration change
183 Not used.
184 Refer to pmFetch(3) for an alternative mechanism that may be used
186 to notify a PCP client when pmcd(1) has experienced one or more
187 configuration changes since the last request from the client. Usu‐
188 ally these changes involve a change to the namespace exported via
189 pmcd and/or changes to the PMDAs under pmcd's control.
190 PM_ERR_FAULT
192 QA fault injected
193 Used only for PCP Quality Assurance (QA) testing.
194 PM_ERR_NYI
196 Functionality not yet implemented
197 Self explanatory and rarely used.
198 PM_ERR_GENERIC
200 Generic error, already reported above
201 Rarely used, this error may be returned when the error condition is
202 a consequent of some earlier returned error and a more precise
203 characterization is not possible.
204
206 These errors may occur in the interactions between a PCP client and
207 pmcd(1) providing real-time performance data.
208 PM_ERR_NOAGENT
210 No PMCD agent for domain of request
211 A request sent to pmcd(1) requires information from an agent or
212 PMDA that does not exist. Usually this means the namespace
213 being used by the client application contains metric names from
214 a previously installed PMDA.
215 PM_ERR_CONNLIMIT
217 PMCD connection limit for this host exceeded
218 The client connection limit for pmcd(1) is controlled by the
219 optional access controls in $PCP_PMCDCONF_PATH. By default
220 there is no limit imposed by the PCP code, and this error would
221 not be seen.
222 PM_ERR_AGAIN
224 Try again. Information not currently available
225 Used to notify a PCP client that the PMDA responsible for deliv‐
226 ering the information is temporarily unavailable. See also
227 PM_ERR_PMDANOTREADY.
228 PM_ERR_NOPROFILE
230 Missing profile - protocol botch
231 Internal error in the communication between a client application
232 and pmcd(1) - should not occur.
233
235 These errors may occur in the interactions between a PCP client and the
236 library routines that provide historical performance data from PCP ar‐
237 chives created by pmlogger(1).
238 PM_ERR_LOGFILE
240 Missing archive file
241 Each PCP archive consists of multiple physical files as
242 described in pmlogger(1). This error occurs when one of the
243 physical files is missing or cannot be opened for reading.
244 PM_ERR_EOL
246 End of PCP archive log
247 An attempt is made to read past the end file of the last volume
248 of a set of PCP archives, or past the end of the time window (as
249 specified with a -T/--finish option) for a set of PCP archives.
250 PM_ERR_NOTHOST
252 Operation requires context with host source of metrics
253 Calls to pmStore(3) require a host context and are not supported
254 for PCP archives.
255 For archives created with versions of PCP prior to 4.0, the
257 pmLookupText(3) and pmLookupInDomText(3) calls will return this
258 code for archive PMAPI contexts (help and one-line text was not
259 previously recorded in archive logs).
260 PM_ERR_LOGREC
262 Corrupted record in a PCP archive log
263 PCP archives can become corrupted for a variety of reasons, but
264 the most common is premature termination of pmlogger(1) without
265 flushing its output buffers.
266 PM_ERR_LABEL
268 Illegal label record at start of a PCP archive log file
269 Each physical file in a PCP archive should begin with a common
270 label record. This is a special case of PM_ERR_LOGREC errors.
271 PM_ERR_NODATA
273 Empty archive log file
274 An empty physical file can never be part of a valid PCP archive
275 (at least the label record should be present). This is a spe‐
276 cial case of PM_ERR_LOGREC errors.
277 PM_ERR_NOTARCHIVE
279 Operation requires context with archive source of metrics
280 A call to one of the archive variant routines, i.e.
281 pmFetchArchive(3), pmGetInDomArchive(3), pmLookupInDomArchive(3)
282 or pmNameInDomArchive(3), when the current context is not asso‐
283 ciated with a set of PCP archives.
284 PM_ERR_PMID_LOG
286 Metric not defined in the PCP archive log
287 A PCP client has requested information about a metric, and there
288 is no corresponding information in the set of PCP archives.
289 This should not happen for well-behaved PCP clients.
290 PM_ERR_INDOM_LOG
292 Instance domain identifier not defined in the PCP archive log
293 A PCP client has requested information about an instance domain
294 for one or more performance metrics, and there is no correspond‐
295 ing information in the set of PCP archives. If the client is
296 using metric descriptors from the set of archives to identify
297 the instance domain, this is less likely to happen.
298 Because instance domains may vary over time, clients may need to
300 use the variant routines pmGetInDomArchive(3) or pmLookupInDo‐
301 mArchive(3) or pmNameInDomArchive(3) to manipulate the union of
302 the instances in an instance domain over the life of an archive.
303 PM_ERR_INST_LOG
305 Instance identifier not defined in the PCP archive log
306 A PCP client has requested information about a specific instance
307 of a performance metric, and there is no corresponding informa‐
308 tion in the set of PCP archives. If the client is using
309 instance names from the instance domain in the set of archives
310 (rather than hard-coded instance names) and instance identifiers
311 from the results returned by pmFetch(3) or pmFetchArchive(3)
312 this is less likely to happen.
313 Because instance domains may vary over time, clients may need to
315 use the variant routines pmLookupInDomArchive(3) or pmNameInDo‐
316 mArchive(3) to manipulate the union of the instances in an
317 instance domain over the life of an archive.
318 PM_ERR_LOGOVERLAP
320 Archives overlap in time
321 When using a context associated with a set of archives, the ar‐
322 chives in the set may not overlap in time.
323 PM_ERR_LOGHOST
325 Archives differ by host
326 When using a context associated with a set of archives, the ar‐
327 chives in the set must all have been generated on the same host.
328 PM_ERR_LOGTIMEZONE
330 Archives differ by time zone
331 When using a context associated with a set of archives, the ar‐
332 chives in the set must all have been generated using the same
333 time zone.
334 PM_ERR_LOGCHANGETYPE
336 The type of a metric differs among archives
337 When using a context associated with a set of archives, the type
338 of each metric must be same in all of the archives.
339 PM_ERR_LOGCHANGESEM
341 The semantics of a metric differs among archives
342 When using a context associated with a set of archives, the
343 semantics of each metric must be same in all of the archives.
344 PM_ERR_LOGCHANGEINDOM
346 The instance domain of a metric differs among archives
347 When using a context associated with a set of archives, the
348 instance domain of each metric must be same in all of the ar‐
349 chives.
350 PM_ERR_LOGCHANGEUNITS
352 The units of a metric differs among archives
353 When using a context associated with a set of archives, the
354 units of each metric must be same in all of the archives.
355
357 These errors may occur in the interactions between a GUI PCP client and
358 the time control services provided by pmtime(1).
359 PM_ERR_ISCONN
361 Already Connected
362 A PCP client application called pmTimeConnect(3) when already
363 connected to a pmtime(1) instance.
364 PM_ERR_NOTCONN
366 Not Connected
367 A PCP client application called one of the time control routines
368 pmTime*[22m(3) when not currently connected to any pmtime(1)
369 instance.
370 PM_ERR_NEEDPORT
372 A non-null port name is required
373 If a shared pmtime(1) instance is being created the port argu‐
374 ment to pmTimeConnect(3) must not be invalid.
375
377 These errors may occur in the processing of PCP namespace operations.
378 A PCP namespace, see pmns(5), provides the external names and the
379 internal identifiers for the available performance metrics.
380 PM_ERR_NONLEAF
382 Metric name is not a leaf in PMNS
383 The metric name passed to pmLookupName(3) names a non-terminal
384 path in the namespace, i.e. a group of metrics rather than a
385 single metric.
386 PM_ERR_DUPPMNS
388 Attempt to reload the PMNS
389 When using an explicit local namespace, it is illegal to call
390 either of pmLoadNameSpace(3) or pmLoadASCIINameSpace(3) more
391 than once.
392 PM_ERR_PMNS
394 Problems parsing PMNS definitions
395 Only occurs when an ASCII namespace is explicitly loaded.
396 PM_ERR_NOPMNS
398 PMNS not accessible
399 Only occurs when an ASCII namespace is explicitly loaded.
400
402 These error codes are used in the interactions between pmcd(1) and the
403 PMDAs that provide the performance data.
404 PM_ERR_PMDANOTREADY
406 PMDA is not yet ready to respond to requests
407 Some PMDAs have long initialization or reset times, and will
408 respond to pmcd(1) with this error if they are busy at the
409 moment. This error translates to PM_ERR_AGAIN for the PCP
410 client who made the request to pmcd which caused the initial
411 request to the PMDA. At some later time the PMDA will inform
412 pmcd (see PM_ERR_PMDAREADY) that it is now ready to process
413 requests, and client requests will begin to succeed.
414 PM_ERR_PMDAREADY
416 PMDA is now responsive to requests
417 Used by PMDAs to asynchronously inform pmcd(1) that they are now
418 willing to resume processing requests. See also PM_ERR_PMDAN‐
419 OTREADY.
420
422 Environment variables with the prefix PCP_ are used to parameterize the
423 file and directory names used by PCP. On each installation, the file
424 /etc/pcp.conf contains the local values for these variables. The
425 $PCP_CONF variable may be used to specify an alternative configuration
426 file, as described in pcp.conf(5). Values for these variables may be
427 obtained programmatically using the pmGetConfig(3) function.
428
430 PCPIntro(1), pmcd(1), pmerr(1), pminfo(1), pmtime(1), pmstore(1),
431 pmlogger(1), PMAPI(3), pmAddProfile(3), pmDelProfile(3), pmConvS‐
432 cale(3), pmNewContext(3), pmDestroyContext(3), pmErrStr(3), pmExtract‐
433 Value(3), pmFetch(3), pmFetchArchive(3), pmGetConfig(3), pmGetInDom(3),
434 pmGetInDomArchive(3), pmLoadNameSpace(3), pmLookupInDom(3), pmLookupIn‐
435 DomText(3), pmLookupName(3), pmLookupText(3), pmNameInDom(3), pmNameIn‐
436 DomArchive(3), pmSetMode(3), pmStore(3), pmTimeConnect(3), pcp.conf(5)
437 and pcp.env(5).
438Performance Co-Pilot PCP PCPINTRO(3)