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 an SGI product designed for monitoring
10 and 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_LICENSE
53 Current PCP license does not permit this operation
54 Some pmcd(1) services require a valid PCP Collector license, and
55 some PCP client applications require a valid PCP Monitor license.
56 The open source version of pmcd(1) does not require any licenses at
57 all.
58 PM_ERR_IPC
60 IPC protocol failure
61 Generic protocol failure on a pipe or socket connecting two PCP
62 applications, eg. client-pmcd, or client-pmtime, or PMDA-pmcd or
63 pmlc-pmlogger.
64 PM_ERR_TEXT
66 Oneline or help text is not available
67 Set by a PMDA, and passed back to a PCP client, to indicate that
68 the PMDA is unable to supply the requested metric or instance
69 domain help text.
70 PM_ERR_VALUE
72 Missing metric value(s)
73 This error is used for a number of conditions in which the value of
74 a performance metric is inappropriate for the context in which it
75 is being used, eg.
76 (a) Bad value for the metric pmcd.timezone when trying to set the
78 timezone via pmNewContextZone(3) for a remote or archive con‐
79 text.
80 (b) Attempting to interpolate values for a metric with non-numeric
82 data type from a PCP archive.
83 (c) A bad result data structure passed to pmStore(3).
85 PM_ERR_FILE
87 Cannot locate a file
88 Generic error when a named file is expected to already exist.
89 PM_ERR_NAME
91 Unknown metric name
92 Just what the message says.
93 PM_ERR_PMID
95 Unknown or illegal metric identifier
96 Just what the message says.
97 PM_ERR_INDOM
99 Unknown or illegal instance domain identifier
100 A request nominates an instance domain that is unknown or
101 PM_INDOM_NULL. May occur as a consequence of the instance domain
102 identifier passed by a PCP client to pmGetInDom(3), pmLookupIn‐
103 Dom(3), pmNameInDom(3), pmGetInDomArchive(3), pmLookupInDo‐
104 mArchive(3), pmNameInDomArchive(3) or a request passed from pmcd(1)
105 to a PMDA.
106 PM_ERR_EOF
108 IPC channel closed
109 End of file on a pipe or socket connecting two PCP applications,
110 eg. client-pmcd, or client-pmtime or PMDA-pmcd.
111 PM_ERR_NOCONTEXT
113 Attempt to use an illegal context
114 Typically caused by a PCP client that tries to make calls before
115 calling pmNewContext(3) or after calling pmDestroyContext(3).
116 PM_ERR_PERMISSION
118 No permission to perform requested operation
119 PCP-specific access controls apply to pmcd(1) and pmlogger(1).
120 Platform-specific permission errors are returned as -EPERM.
121 PM_ERR_CONV
123 Impossible value or scale conversion
124 Some value conversion requests are illegal, eg. bad debug flag sym‐
125 bolic name for -D option, or asking pmExtractValue(3) to translate
126 non-numeric data types to numbers and vice versa.
127 PM_ERR_TRUNC
129 Truncation in value conversion
130 Some conversion requests to pmExtractValue(3) cannot be performed
131 based on the metric types and values involved, in this case conver‐
132 sion would result in loss of precision.
133 PM_ERR_SIGN
135 Negative value in conversion to unsigned
136 Some conversion requests to pmExtractValue(3) cannot be performed
137 based on the metric types and values involved, in this case con‐
138 verting a negative value to an unsigned value.
139 PM_ERR_UNIT
141 Illegal pmUnits specification
142 Some conversion requests to pmConvScale(3) cannot be performed due
143 to illegal or incompatible specifications of the source and desti‐
144 nation units.
145 PM_ERR_PROFILE
147 Explicit instance identifier(s) required
148 Some PMDAs, especially the proc PMDA, will not return ``all
149 instances'' for a pmFetch(3) request due to the cost. The client
150 must explicitly built an instance profile using pmAddProfile(3)
151 and/or pmDelProfile(3) before calling pmFetch(3). See also the -F
152 option to pminfo(1).
153 PM_ERR_MODE
155 Illegal mode specification
156 Illegal mode argument to pmSetMode(3).
157 PM_ERR_PROFILESPEC
159 NULL pmInDom with non-NULL instlist
160 Bad arguments passed from a PCP client to pmAddProfile(3).
161 PM_ERR_OBJSTYLE
163 Caller does not match object style of running kernel
164 In some cases, a PCP application must be build with the same object
165 code style as the booted kernel because direct access to kernel
166 data structures may be required. These cases are a client using
167 PM_CONTEXT_LOCAL, or pmcd(1), or a DSO-style PMDA to be used by
168 pmcd.
169 PM_ERR_TOOSMALL
171 Insufficient elements in list
172 Parameter passing error by caller specifying a list with less than
173 one element to pmFetch(3), pmLookupName(3) or pmStore(3).
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_NOASCII
192 ASCII format not supported for this PDU
193 The ASCII mode PDU support is intended for use only between pmcd
194 and a PMDA. Consequently not all of the possible PDU types include
195 encode and decode support for ASCII PDUs.
196 PM_ERR_NYI
198 Functionality not yet implemented
199 Self explanatory and rarely used.
200 PM_ERR_GENERIC
202 Generic error, already reported above
203 Rarely used, this error may be returned when the error condition is
204 a consequent of some earlier returned error and a more precise
205 characterization is not possible.
206
208 These errors may occur in the interactions between a PCP client and
209 pmcd(1) providing real-time performance data.
210 PM_ERR_INST
212 Unknown or illegal instance identifier
213 A request to a PMDA nominates an instance that is unknown. May
214 occur as a consequence of the profile established prior to a
215 pmFetch(3) call, or an explicit instance name or identifier to
216 pmLookupInDom(3) or pmNameInDom(3).
217 PM_ERR_NOAGENT
219 No PMCD agent for domain of request
220 A request sent to pmcd(1) requires information from an agent or
221 PMDA that does not exist. Usually this means the namespace
222 being used by the client application contains metric names from
223 a previously installed PMDA.
224 PM_ERR_CONNLIMIT
226 PMCD connection limit for this host exceeded
227 The client connection limit for pmcd(1) is controlled by the
228 optional access controls in $PCP_PMCDCONF_PATH. By default
229 there is no limit imposed by the PCP code, and this error would
230 not be seen.
231 PM_ERR_AGAIN
233 Try again. Information not currently available
234 Used to notify a PCP client that the PMDA responsible for deliv‐
235 ering the information is temporarily unavailable. See also
236 PM_ERR_PMDANOTREADY.
237 PM_ERR_PMCDLICENSE
239 PMCD is not licensed to accept client connections
240 If pmcd(1) is running without a valid PCP Collector License,
241 then it will only accept connections from ``authorized'' PCP
242 clients like pminfo(1) or pmlogger(1). This error occurs when
243 an unauthorized PCP client attempts to connect to an unlicensed
244 pmcd(1).
245 PM_ERR_NOPROFILE
247 Missing profile - protocol botch
248 Internal error in the communication between a client application
249 and pmcd(1) - should not occur.
250
252 These errors may occur in the interactions between a PCP client and the
253 library routines that provide historical performance data from PCP ar‐
254 chives created by pmlogger(1).
255 PM_ERR_EOL
257 End of PCP archive log
258 An attempt is made to read past the end file of the last volume
259 of a PCP archive, or past the end of the time window (as speci‐
260 fied with a -T option) for a PCP archive.
261 PM_ERR_NOTHOST
263 Operation requires context with host source of metrics
264 Operations involving help text (ie. pmLookupText(3) and
265 pmLookupInDomText(3)) or calls to pmStore(3) require a host con‐
266 text and are not supported for PCP archives.
267 PM_ERR_LOGREC
269 Corrupted record in a PCP archive log
270 PCP archives can become corrupted for a variety of reasons, but
271 the most common is premature termination of pmlogger(1) without
272 flushing its output buffers.
273 PM_ERR_LABEL
275 Illegal label record at start of a PCP archive log file
276 Each physical file in a PCP archive should begin with a common
277 label record. This is a special case of PM_ERR_LOGREC errors.
278 PM_ERR_NODATA
280 Empty archive log file
281 An empty physical file can never be part of a valid PCP archive
282 (at least the label record should be present). This is a spe‐
283 cial case of PM_ERR_LOGREC errors.
284 PM_ERR_NOTARCHIVE
286 Operation requires context with archive source of metrics
287 A call to one of the archive variant routines, i.e.
288 pmFetchArchive(3), pmGetInDomArchive(3), pmLookupInDomArchive(3)
289 or pmNameInDomArchive(3), when the current context is not asso‐
290 ciated with a PCP archive.
291 PM_ERR_PMID_LOG
293 Metric not defined in the PCP archive log
294 A PCP client has requested information about a metric, and there
295 is no corresponding information in the PCP archive. This should
296 not happen for well-behaved PCP clients.
297 PM_ERR_INDOM_LOG
299 Instance domain identifier not defined in the PCP archive log
300 A PCP client has requested information about an instance domain
301 for one or more performance metrics, and there is no correspond‐
302 ing information in the PCP archive. If the client is using met‐
303 ric descriptors from the archive to identify the instance
304 domain, this is less likely to happen.
305 Because instance domains may vary over time, clients may need to
307 use the variant routines pmGetInDomArchive(3) or pmLookupInDo‐
308 mArchive(3) or pmNameInDomArchive(3) to manipulate the union of
309 the instances in an instance domain over the life of an archive.
310 PM_ERR_INST_LOG
312 Instance identifier not defined in the PCP archive log
313 A PCP client has requested information about a specific instance
314 of a performance metric, and there is no corresponding informa‐
315 tion in the PCP archive. If the client is using instance names
316 from the instance domain in the archive (rather than hard-coded
317 instance names) and instance identifiers from the results
318 returned by pmFetch(3) or pmFetchArchive(3) this is less likely
319 to happen.
320 Because instance domains may vary over time, clients may need to
322 use the variant routines pmLookupInDomArchive(3) or pmNameInDo‐
323 mArchive(3) to manipulate the union of the instances in an
324 instance domain over the life of an archive.
325
327 These errors may occur in the interactions between a GUI PCP client and
328 the time control services provided by pmtime(1).
329 PM_ERR_ISCONN
331 Already Connected
332 A PCP client application called pmTimeConnect(3) when already
333 connected to a pmtime(1) instance.
334 PM_ERR_NOTCONN
336 Not Connected
337 A PCP client application called one of the time control routines
338 pmTime*[22m(3) when not currently connected to any pmtime(1)
339 instance.
340 PM_ERR_NEEDPORT
342 A non-null port name is required
343 If a shared pmtime(1) instance is being created the port argu‐
344 ment to pmTimeConnect(3) must not be invalid.
345 PM_ERR_WANTACK
347 Cannot send due to pending acknowledgements
348 Some client of pmtime(1) is not acknowledging messages from
349 pmtime, and this is causing other clients to be blocked.
350
352 These errors may occur in the processing of PCP namespace operations.
353 A PCP namespace, see pmns(4), provides the external names and the
354 internal identifiers for the available performance metrics.
355 PM_ERR_NONLEAF
357 Metric name is not a leaf in PMNS
358 The metric name passed to pmLookupName(3) names a non-terminal
359 path in the namespace, i.e. a group of metrics rather than a
360 single metric.
361 PM_ERR_DUPPMNS
363 Attempt to reload the PMNS
364 When using an explicit local namespace, it is illegal to call
365 either of pmLoadNameSpace(3) or pmLoadASCIINameSpace(3) more
366 than once.
367 PM_ERR_PMNS
369 Problems parsing PMNS definitions
370 Only occurs when an ASCII namespace is loaded. As of PCP 2.0
371 this error is mostly confined to pmnscomp(1) and client applica‐
372 tions that use an uncompiled namespace file with a -n option.
373 PM_ERR_NOPMNS
375 PMNS not accessible
376 Only occurs when an ASCII namespace is loaded. As of PCP 2.0
377 this error is mostly confined to pmnscomp(1) and client applica‐
378 tions that use an uncompiled namespace file with a -n option.
379
381 These error codes are used in the interactions between pmcd(1) and the
382 PMDAs that provide the performance data.
383 PM_ERR_PMDANOTREADY
385 PMDA is not yet ready to respond to requests
386 Some PMDAs have long initialization or reset times, and will
387 respond to pmcd(1) with this error if they are busy at the
388 moment. This error translates to PM_ERR_AGAIN for the PCP
389 client who made the request to pmcd which caused the initial
390 request to the PMDA. At some later time the PMDA will inform
391 pmcd (see PM_ERR_PMDAREADY) that it is now ready to process
392 requests, and client requests will begin to succeed.
393 PM_ERR_PMDAREADY
395 PMDA is now responsive to requests
396 Used by PMDAs to asynchronously inform pmcd(1) that they are now
397 willing to resume processing requests. See also PM_ERR_PMDAN‐
398 OTREADY.
399
401 Environment variables with the prefix PCP_ are used to parameterize the
402 file and directory names used by PCP. On each installation, the file
403 /etc/pcp.conf contains the local values for these variables. The
404 $PCP_CONF variable may be used to specify an alternative configuration
405 file, as described in pcp.conf(4). Values for these variables may be
406 obtained programatically using the pmGetConfig(3) function.
407
409 pmerr(1), PMAPI(3), pmErrStr(3), pmGetConfig(3), pcp.conf(4) and
410 pcp.env(4).
411Performance Co-Pilot SGI PCPINTRO(3)