1PCPINTRO(3)                Library Functions Manual                PCPINTRO(3)
2
3
4

NAME

6       PCPIntro - introduction to the Performance Co-Pilot (PCP) libraries
7

INTRODUCTION

9       Performance  Co-Pilot  (PCP)  is  a toolkit designed for monitoring and
10       managing system-level performance.
11
12       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
17       Individual library routines are documented in their own manual page en‐
18       tries.
19
20       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

GENERAL ERRORS

29       These common errors may occur in various PCP interactions.
30
31       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
38           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
44       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
52       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
58       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
64       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
70           (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
74           (b) Attempting  to interpolate values for a metric with non-numeric
75               data type from a set of PCP archives.
76
77           (c) A bad result data structure passed to pmStore(3).
78
79       PM_ERR_NAME
80           Unknown metric name
81           Just what the message says.
82
83       PM_ERR_PMID
84           Unknown or illegal metric identifier
85           Just what the message says.
86
87       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
95       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
100       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
105       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
110       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
116       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
122       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
128       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
135       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
141       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
149       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
156       PM_ERR_MODE
157           Illegal mode specification
158           Illegal mode argument to pmSetMode(3).
159
160       PM_ERR_PROFILESPEC
161           NULL pmInDom with non-NULL instlist
162           Bad arguments passed from a PCP client to pmAddProfile(3).
163
164       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
169       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
175       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
180       PM_ERR_NOCONTAINER
181           Container not found The user supplied container name does not match
182           any known container.
183
184       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
190       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
196       PM_ERR_RESET
197           PMCD reset or configuration change
198           Not used.
199
200           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
206       PM_ERR_FAULT
207           QA fault injected
208           Used only for PCP Quality Assurance (QA) testing.
209
210       PM_ERR_NYI
211           Functionality not yet implemented
212           Self explanatory and rarely used.
213
214       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
220       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
225       PM_ERR_NOLABELS
226           No support for metric label metadata
227           Operation requires metric labels, but none are available.
228

CLIENT-PMCD ERRORS

230       These  errors  may  occur  in the interactions between a PCP client and
231       pmcd(1) providing real-time performance data.
232
233       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
240       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
247       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
253       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
258       PM_ERR_NEEDCLIENTCERT
259              PMCD requires a client certificate Authentication failure.
260
261       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

CLIENT-ARCHIVE ERRORS

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
273       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
279       PM_ERR_EOL
280              End of PCP archive log
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
285       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
290              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 archive logs).
294
295       PM_ERR_LOGREC
296              Corrupted record in a PCP archive log
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
301       PM_ERR_LABEL
302              Illegal label record at start of a PCP archive log 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
306       PM_ERR_NODATA
307              Empty archive log 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
312       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
319       PM_ERR_PMID_LOG
320              Metric not defined in the PCP archive log
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
325       PM_ERR_INDOM_LOG
326              Instance domain identifier not defined in the PCP archive log
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
333              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
338       PM_ERR_INST_LOG
339              Instance identifier not defined in the PCP archive log
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
348              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
353       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
358       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
363       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
368       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
373       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
379       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

TIME CONTROL ERRORS

385       These errors may occur in the interactions between a GUI PCP client and
386       the time control services provided by pmtime(1).
387
388       PM_ERR_ISCONN
389              Already Connected
390              A PCP client application called  pmTimeConnect(3)  when  already
391              connected to a pmtime(1) instance.
392
393       PM_ERR_NOTCONN
394              Not Connected
395              A PCP client application called one of the time control routines
396              pmTime*(3) when not currently connected  to  any  pmtime(1)  in‐
397              stance.
398
399       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

NAMESPACE ERRORS

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
409       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
415       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
421       PM_ERR_PMNS
422              Problems parsing PMNS definitions
423              Only occurs when an ASCII namespace is explicitly loaded.
424
425       PM_ERR_NOPMNS
426              PMNS not accessible
427              Only occurs when an ASCII namespace is explicitly loaded.
428

PMCD-PMDA ERRORS

430       These error codes are used in the interactions between pmcd(1) and  the
431       PMDAs that provide the performance data.
432
433       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
443       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

PCP ENVIRONMENT

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

SEE ALSO

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).
466
467
468
469Performance Co-Pilot                  PCP                          PCPINTRO(3)
Impressum