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 PCP archive.
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 option, or asking pmExtractValue(3) to translate
115 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 -F
148 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 PCP archive, or past the end of the time window (as speci‐
249 fied with a -T option) for a PCP archive.
250 PM_ERR_NOTHOST
252 Operation requires context with host source of metrics
253 Operations involving help text (ie. pmLookupText(3) and
254 pmLookupInDomText(3)) or calls to pmStore(3) require a host con‐
255 text and are not supported for PCP archives.
256 PM_ERR_LOGREC
258 Corrupted record in a PCP archive log
259 PCP archives can become corrupted for a variety of reasons, but
260 the most common is premature termination of pmlogger(1) without
261 flushing its output buffers.
262 PM_ERR_LABEL
264 Illegal label record at start of a PCP archive log file
265 Each physical file in a PCP archive should begin with a common
266 label record. This is a special case of PM_ERR_LOGREC errors.
267 PM_ERR_NODATA
269 Empty archive log file
270 An empty physical file can never be part of a valid PCP archive
271 (at least the label record should be present). This is a spe‐
272 cial case of PM_ERR_LOGREC errors.
273 PM_ERR_NOTARCHIVE
275 Operation requires context with archive source of metrics
276 A call to one of the archive variant routines, i.e.
277 pmFetchArchive(3), pmGetInDomArchive(3), pmLookupInDomArchive(3)
278 or pmNameInDomArchive(3), when the current context is not asso‐
279 ciated with a PCP archive.
280 PM_ERR_PMID_LOG
282 Metric not defined in the PCP archive log
283 A PCP client has requested information about a metric, and there
284 is no corresponding information in the PCP archive. This should
285 not happen for well-behaved PCP clients.
286 PM_ERR_INDOM_LOG
288 Instance domain identifier not defined in the PCP archive log
289 A PCP client has requested information about an instance domain
290 for one or more performance metrics, and there is no correspond‐
291 ing information in the PCP archive. If the client is using met‐
292 ric descriptors from the archive to identify the instance
293 domain, this is less likely to happen.
294 Because instance domains may vary over time, clients may need to
296 use the variant routines pmGetInDomArchive(3) or pmLookupInDo‐
297 mArchive(3) or pmNameInDomArchive(3) to manipulate the union of
298 the instances in an instance domain over the life of an archive.
299 PM_ERR_INST_LOG
301 Instance identifier not defined in the PCP archive log
302 A PCP client has requested information about a specific instance
303 of a performance metric, and there is no corresponding informa‐
304 tion in the PCP archive. If the client is using instance names
305 from the instance domain in the archive (rather than hard-coded
306 instance names) and instance identifiers from the results
307 returned by pmFetch(3) or pmFetchArchive(3) this is less likely
308 to happen.
309 Because instance domains may vary over time, clients may need to
311 use the variant routines pmLookupInDomArchive(3) or pmNameInDo‐
312 mArchive(3) to manipulate the union of the instances in an
313 instance domain over the life of an archive.
314
316 These errors may occur in the interactions between a GUI PCP client and
317 the time control services provided by pmtime(1).
318 PM_ERR_ISCONN
320 Already Connected
321 A PCP client application called pmTimeConnect(3) when already
322 connected to a pmtime(1) instance.
323 PM_ERR_NOTCONN
325 Not Connected
326 A PCP client application called one of the time control routines
327 pmTime*[22m(3) when not currently connected to any pmtime(1)
328 instance.
329 PM_ERR_NEEDPORT
331 A non-null port name is required
332 If a shared pmtime(1) instance is being created the port argu‐
333 ment to pmTimeConnect(3) must not be invalid.
334
336 These errors may occur in the processing of PCP namespace operations.
337 A PCP namespace, see pmns(5), provides the external names and the
338 internal identifiers for the available performance metrics.
339 PM_ERR_NONLEAF
341 Metric name is not a leaf in PMNS
342 The metric name passed to pmLookupName(3) names a non-terminal
343 path in the namespace, i.e. a group of metrics rather than a
344 single metric.
345 PM_ERR_DUPPMNS
347 Attempt to reload the PMNS
348 When using an explicit local namespace, it is illegal to call
349 either of pmLoadNameSpace(3) or pmLoadASCIINameSpace(3) more
350 than once.
351 PM_ERR_PMNS
353 Problems parsing PMNS definitions
354 Only occurs when an ASCII namespace is explicitly loaded.
355 PM_ERR_NOPMNS
357 PMNS not accessible
358 Only occurs when an ASCII namespace is explicitly loaded.
359
361 These error codes are used in the interactions between pmcd(1) and the
362 PMDAs that provide the performance data.
363 PM_ERR_PMDANOTREADY
365 PMDA is not yet ready to respond to requests
366 Some PMDAs have long initialization or reset times, and will
367 respond to pmcd(1) with this error if they are busy at the
368 moment. This error translates to PM_ERR_AGAIN for the PCP
369 client who made the request to pmcd which caused the initial
370 request to the PMDA. At some later time the PMDA will inform
371 pmcd (see PM_ERR_PMDAREADY) that it is now ready to process
372 requests, and client requests will begin to succeed.
373 PM_ERR_PMDAREADY
375 PMDA is now responsive to requests
376 Used by PMDAs to asynchronously inform pmcd(1) that they are now
377 willing to resume processing requests. See also PM_ERR_PMDAN‐
378 OTREADY.
379
381 Environment variables with the prefix PCP_ are used to parameterize the
382 file and directory names used by PCP. On each installation, the file
383 /etc/pcp.conf contains the local values for these variables. The
384 $PCP_CONF variable may be used to specify an alternative configuration
385 file, as described in pcp.conf(5). Values for these variables may be
386 obtained programmatically using the pmGetConfig(3) function.
387
389 pmerr(1), PMAPI(3), pmErrStr(3), pmGetConfig(3), pcp.conf(5) and
390 pcp.env(5).
391Performance Co-Pilot PCP PCPINTRO(3)