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
18       entries.
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
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

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
55           applications, eg. client-pmcd, or client-pmtime,  or  PMDA-pmcd  or
56           pmlc-pmlogger.
57
58       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
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
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
96       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
101       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
106       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
111       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
117       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
123       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
129       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
136       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
142       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
150       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
157       PM_ERR_MODE
158           Illegal mode specification
159           Illegal mode argument to pmSetMode(3).
160
161       PM_ERR_PROFILESPEC
162           NULL pmInDom with non-NULL instlist
163           Bad arguments passed from a PCP client to pmAddProfile(3).
164
165       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
170       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
175       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
181       PM_ERR_RESET
182           PMCD reset or configuration change
183           Not used.
184
185           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
191       PM_ERR_FAULT
192           QA fault injected
193           Used only for PCP Quality Assurance (QA) testing.
194
195       PM_ERR_NYI
196           Functionality not yet implemented
197           Self explanatory and rarely used.
198
199       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

CLIENT-PMCD ERRORS

206       These errors may occur in the interactions between  a  PCP  client  and
207       pmcd(1) providing real-time performance data.
208
209       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
216       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
223       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
229       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

CLIENT-ARCHIVE ERRORS

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
239       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
245       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
251       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
256              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
261       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
267       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
272       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
278       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
285       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
291       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
299              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
304       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
314              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
319       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
324       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
329       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
335       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
340       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
345       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
351       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

TIME CONTROL ERRORS

357       These errors may occur in the interactions between a GUI PCP client and
358       the time control services provided by pmtime(1).
359
360       PM_ERR_ISCONN
361              Already Connected
362              A PCP client application called  pmTimeConnect(3)  when  already
363              connected to a pmtime(1) instance.
364
365       PM_ERR_NOTCONN
366              Not Connected
367              A PCP client application called one of the time control routines
368              pmTime*(3)  when  not  currently  connected  to  any   pmtime(1)
369              instance.
370
371       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

NAMESPACE ERRORS

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
381       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
387       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
393       PM_ERR_PMNS
394              Problems parsing PMNS definitions
395              Only occurs when an ASCII namespace is explicitly loaded.
396
397       PM_ERR_NOPMNS
398              PMNS not accessible
399              Only occurs when an ASCII namespace is explicitly loaded.
400

PMCD-PMDA ERRORS

402       These error codes are used in the interactions between pmcd(1) and  the
403       PMDAs that provide the performance data.
404
405       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
415       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

PCP ENVIRONMENT

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

SEE ALSO

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).
438
439
440
441Performance Co-Pilot                  PCP                          PCPINTRO(3)
Impressum