Man Linux: Main Page and Category List

NAME

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

INTRODUCTION

       Performance  Co-Pilot  (PCP)  is an SGI product designed for monitoring
       and managing system-level performance.

       The PCP libraries support the APIs required to create  new  performance
       monitoring  tools and new agents (or PMDAs) to export performance data.
       The libpcp library is used in both cases.  The libpcp_pmda  library  is
       used only for PMDAs.

       Individual  library  routines  are  documented in their own manual page
       entries.

       Most routines return an integer value; greater than equal to  zero  for
       success and less than zero for an error.  The error codes have symbolic
       names defined in <pcp/pmapi.h>.  Other  negative  values  are  used  to
       encode  errors  that  can  be  mapped  to  the traditional errno values
       defined in <errno.h>, with the value negated.   To  translate  all  PCP
       error  codes  into  useful messages use either pmerr(1) or pmErrStr(3);
       the latter may also be used to decode the -errno cases.

GENERAL ERRORS

       These common errors may occur in various PCP interactions.

       PM_ERR_TIMEOUT
           Timeout waiting for a response from PMCD
           Many interactions  between  PCP  applications  involve  synchronous
           message  passing,  and  these  are  subject to timeout constraints.
           These errors are most frequently  encountered  when  using  network
           connections with slow data rates or long latencies.

           For  client-pmcd  timeouts,  refer  to  PCPIntro(1) for environment
           variables that may be used to modify the timeout  thresholds.   For
           pmcd-PMDA  timeouts  refer  to the -t and -q options of pmcd(1) and
           the PCP metric pmcd.control.timeout that can be dynamically changed
           with pmstore(1).

       PM_ERR_APPVERSION
           Metric not supported by this version of monitored application
           Some  performance metrics are unavailable from specific versions of
           the associated PMDA, or may be unavailable because  the  underlying
           instrumentation  has changed or is not installed or is not enabled.
           This error is used in results from  pmFetch(3)  to  indicate  these
           situations.

       PM_ERR_LICENSE
           Current PCP license does not permit this operation
           Some  pmcd(1)  services  require a valid PCP Collector license, and
           some PCP client applications require a valid PCP  Monitor  license.
           The open source version of pmcd(1) does not require any licenses at
           all.

       PM_ERR_IPC
           IPC protocol failure
           Generic protocol failure on a pipe or  socket  connecting  two  PCP
           applications,  eg.  client-pmcd,  or client-pmtime, or PMDA-pmcd or
           pmlc-pmlogger.

       PM_ERR_TEXT
           Oneline or help text is not available
           Set by a PMDA, and passed back to a PCP client,  to  indicate  that
           the  PMDA  is  unable  to  supply  the requested metric or instance
           domain help text.

       PM_ERR_VALUE
           Missing metric value(s)
           This error is used for a number of conditions in which the value of
           a  performance  metric is inappropriate for the context in which it
           is being used, eg.

           (a) Bad value for the metric pmcd.timezone when trying to  set  the
               timezone  via  pmNewContextZone(3)  for  a  remote  or  archive
               context.

           (b) Attempting to interpolate values for a metric with  non-numeric
               data type from a PCP archive.

           (c) A bad result data structure passed to pmStore(3).

       PM_ERR_FILE
           Cannot locate a file
           Generic error when a named file is expected to already exist.

       PM_ERR_NAME
           Unknown metric name
           Just what the message says.

       PM_ERR_PMID
           Unknown or illegal metric identifier
           Just what the message says.

       PM_ERR_INDOM
           Unknown or illegal instance domain identifier
           A   request  nominates  an  instance  domain  that  is  unknown  or
           PM_INDOM_NULL.  May occur as a consequence of the  instance  domain
           identifier    passed    by   a   PCP   client   to   pmGetInDom(3),
           pmLookupInDom(3),       pmNameInDom(3),       pmGetInDomArchive(3),
           pmLookupInDomArchive(3),  pmNameInDomArchive(3) or a request passed
           from pmcd(1) to a PMDA.

       PM_ERR_EOF
           IPC channel closed
           End of file on a pipe or socket connecting  two  PCP  applications,
           eg. client-pmcd, or client-pmtime or PMDA-pmcd.

       PM_ERR_NOCONTEXT
           Attempt to use an illegal context
           Typically  caused  by  a PCP client that tries to make calls before
           calling pmNewContext(3) or after calling pmDestroyContext(3).

       PM_ERR_PERMISSION
           No permission to perform requested operation
           PCP-specific access controls  apply  to  pmcd(1)  and  pmlogger(1).
           Platform-specific permission errors are returned as -EPERM.

       PM_ERR_CONV
           Impossible value or scale conversion
           Some  value  conversion  requests  are  illegal, eg. bad debug flag
           symbolic  name  for  -D  option,  or  asking  pmExtractValue(3)  to
           translate non-numeric data types to numbers and vice versa.

       PM_ERR_TRUNC
           Truncation in value conversion
           Some  conversion  requests to pmExtractValue(3) cannot be performed
           based on the  metric  types  and  values  involved,  in  this  case
           conversion would result in loss of precision.

       PM_ERR_SIGN
           Negative value in conversion to unsigned
           Some  conversion  requests to pmExtractValue(3) cannot be performed
           based on the  metric  types  and  values  involved,  in  this  case
           converting a negative value to an unsigned value.

       PM_ERR_UNIT
           Illegal pmUnits specification
           Some  conversion requests to pmConvScale(3) cannot be performed due
           to  illegal  or  incompatible  specifications  of  the  source  and
           destination units.

       PM_ERR_PROFILE
           Explicit instance identifier(s) required
           Some  PMDAs,  especially  the  proc  PMDA,  will  not  return ‘‘all
           instances’’ for a pmFetch(3) request due to the cost.   The  client
           must  explicitly  built  an  instance profile using pmAddProfile(3)
           and/or pmDelProfile(3) before calling pmFetch(3).  See also the  -F
           option to pminfo(1).

       PM_ERR_MODE
           Illegal mode specification
           Illegal mode argument to pmSetMode(3).

       PM_ERR_PROFILESPEC
           NULL pmInDom with non-NULL instlist
           Bad arguments passed from a PCP client to pmAddProfile(3).

       PM_ERR_OBJSTYLE
           Caller does not match object style of running kernel
           In some cases, a PCP application must be build with the same object
           code style as the booted kernel because  direct  access  to  kernel
           data  structures  may  be required.  These cases are a client using
           PM_CONTEXT_LOCAL, or pmcd(1), or a DSO-style PMDA  to  be  used  by
           pmcd.

       PM_ERR_TOOSMALL
           Insufficient elements in list
           Parameter  passing error by caller specifying a list with less than
           one element to pmFetch(3), pmLookupName(3) or pmStore(3).

       PM_ERR_TOOBIG
           Result size exceeded
           Indicates a fatal error in the message (or  PDU)  passing  protocol
           between two PCP applications.  This is an internal error, and other
           than an exotic networking failure, should not occur.

       PM_ERR_RESET
           PMCD reset or configuration change
           Not used.

           Refer to pmFetch(3) for an alternative mechanism that may  be  used
           to  notify  a  PCP  client when pmcd(1) has experienced one or more
           configuration changes since  the  last  request  from  the  client.
           Usually  these  changes  involve a change to the namespace exported
           via pmcd and/or changes to the PMDAs under pmcd’s control.

       PM_ERR_NOASCII
           ASCII format not supported for this PDU
           The ASCII mode PDU support is intended for use  only  between  pmcd
           and a PMDA.  Consequently not all of the possible PDU types include
           encode and decode support for ASCII PDUs.

       PM_ERR_NYI
           Functionality not yet implemented
           Self explanatory and rarely used.

       PM_ERR_GENERIC
           Generic error, already reported above
           Rarely used, this error may be returned when the error condition is
           a  consequent  of  some  earlier  returned error and a more precise
           characterization is not possible.

CLIENT-PMCD ERRORS

       These errors may occur in the interactions between  a  PCP  client  and
       pmcd(1) providing real-time performance data.

       PM_ERR_INST
              Unknown or illegal instance identifier
              A  request to a PMDA nominates an instance that is unknown.  May
              occur as a consequence of the profile  established  prior  to  a
              pmFetch(3)  call,  or an explicit instance name or identifier to
              pmLookupInDom(3) or pmNameInDom(3).

       PM_ERR_NOAGENT
              No PMCD agent for domain of request
              A request sent to pmcd(1) requires information from an agent  or
              PMDA  that  does  not  exist.   Usually this means the namespace
              being used by the client application contains metric names  from
              a previously installed PMDA.

       PM_ERR_CONNLIMIT
              PMCD connection limit for this host exceeded
              The  client  connection  limit  for pmcd(1) is controlled by the
              optional access  controls  in  $PCP_PMCDCONF_PATH.   By  default
              there  is no limit imposed by the PCP code, and this error would
              not be seen.

       PM_ERR_AGAIN
              Try again. Information not currently available
              Used to notify a  PCP  client  that  the  PMDA  responsible  for
              delivering the information is temporarily unavailable.  See also
              PM_ERR_PMDANOTREADY.

       PM_ERR_PMCDLICENSE
              PMCD is not licensed to accept client connections
              If pmcd(1) is running without a  valid  PCP  Collector  License,
              then  it  will  only  accept connections from ‘‘authorized’’ PCP
              clients like pminfo(1) or pmlogger(1).  This error  occurs  when
              an  unauthorized PCP client attempts to connect to an unlicensed
              pmcd(1).

       PM_ERR_NOPROFILE
              Missing profile - protocol botch
              Internal error in the communication between a client application
              and pmcd(1) - should not occur.

CLIENT-ARCHIVE ERRORS

       These errors may occur in the interactions between a PCP client and the
       library routines that provide  historical  performance  data  from  PCP
       archives created by pmlogger(1).

       PM_ERR_EOL
              End of PCP archive log
              An  attempt is made to read past the end file of the last volume
              of a PCP archive, or  past  the  end  of  the  time  window  (as
              specified with a -T option) for a PCP archive.

       PM_ERR_NOTHOST
              Operation requires context with host source of metrics
              Operations   involving   help   text  (ie.  pmLookupText(3)  and
              pmLookupInDomText(3)) or calls  to  pmStore(3)  require  a  host
              context and are not supported for PCP archives.

       PM_ERR_LOGREC
              Corrupted record in a PCP archive log
              PCP  archives can become corrupted for a variety of reasons, but
              the most common is premature termination of pmlogger(1)  without
              flushing its output buffers.

       PM_ERR_LABEL
              Illegal label record at start of a PCP archive log file
              Each  physical  file in a PCP archive should begin with a common
              label record.  This is a special case of PM_ERR_LOGREC errors.

       PM_ERR_NODATA
              Empty archive log file
              An empty physical file can never be part of a valid PCP  archive
              (at  least  the  label  record  should  be  present).  This is a
              special case of PM_ERR_LOGREC errors.

       PM_ERR_NOTARCHIVE
              Operation requires context with archive source of metrics
              A  call  to  one  of  the   archive   variant   routines,   i.e.
              pmFetchArchive(3), pmGetInDomArchive(3), pmLookupInDomArchive(3)
              or  pmNameInDomArchive(3),  when  the  current  context  is  not
              associated with a PCP archive.

       PM_ERR_PMID_LOG
              Metric not defined in the PCP archive log
              A PCP client has requested information about a metric, and there
              is no corresponding information in the PCP archive.  This should
              not happen for well-behaved PCP clients.

       PM_ERR_INDOM_LOG
              Instance domain identifier not defined in the PCP archive log
              A  PCP client has requested information about an instance domain
              for  one  or  more  performance  metrics,  and   there   is   no
              corresponding  information in the PCP archive.  If the client is
              using metric  descriptors  from  the  archive  to  identify  the
              instance domain, this is less likely to happen.

              Because instance domains may vary over time, clients may need to
              use    the    variant    routines    pmGetInDomArchive(3)     or
              pmLookupInDomArchive(3)  or  pmNameInDomArchive(3) to manipulate
              the union of the instances in an instance domain over  the  life
              of an archive.

       PM_ERR_INST_LOG
              Instance identifier not defined in the PCP archive log
              A PCP client has requested information about a specific instance
              of  a  performance  metric,  and  there  is   no   corresponding
              information in the PCP archive.  If the client is using instance
              names from the instance domain in the archive (rather than hard-
              coded  instance names) and instance identifiers from the results
              returned by pmFetch(3) or pmFetchArchive(3) this is less  likely
              to happen.

              Because instance domains may vary over time, clients may need to
              use   the   variant    routines    pmLookupInDomArchive(3)    or
              pmNameInDomArchive(3)  to  manipulate the union of the instances
              in an instance domain over the life of an archive.

TIME CONTROL ERRORS

       These errors may occur in the interactions between a GUI PCP client and
       the time control services provided by pmtime(1).

       PM_ERR_ISCONN
              Already Connected
              A  PCP  client  application called pmTimeConnect(3) when already
              connected to a pmtime(1) instance.

       PM_ERR_NOTCONN
              Not Connected
              A PCP client application called one of the time control routines
              pmTime*(3)   when  not  currently  connected  to  any  pmtime(1)
              instance.

       PM_ERR_NEEDPORT
              A non-null port name is required
              If a  shared  pmtime(1)  instance  is  being  created  the  port
              argument to pmTimeConnect(3) must not be invalid.

       PM_ERR_WANTACK
              Cannot send due to pending acknowledgements
              Some  client  of  pmtime(1)  is  not acknowledging messages from
              pmtime, and this is causing other clients to be blocked.

NAMESPACE ERRORS

       These errors may occur in the processing of PCP  namespace  operations.
       A  PCP  namespace,  see  pmns(4),  provides  the external names and the
       internal identifiers for the available performance metrics.

       PM_ERR_NONLEAF
              Metric name is not a leaf in PMNS
              The metric name passed to pmLookupName(3) names  a  non-terminal
              path  in  the  namespace,  i.e. a group of metrics rather than a
              single metric.

       PM_ERR_DUPPMNS
              Attempt to reload the PMNS
              When using an explicit local namespace, it is  illegal  to  call
              either  of  pmLoadNameSpace(3)  or  pmLoadASCIINameSpace(3) more
              than once.

       PM_ERR_PMNS
              Problems parsing PMNS definitions
              Only occurs when an ASCII namespace is loaded.  As  of  PCP  2.0
              this   error  is  mostly  confined  to  pmnscomp(1)  and  client
              applications that use an uncompiled namespace  file  with  a  -n
              option.

       PM_ERR_NOPMNS
              PMNS not accessible
              Only  occurs  when  an ASCII namespace is loaded.  As of PCP 2.0
              this  error  is  mostly  confined  to  pmnscomp(1)  and   client
              applications  that  use  an  uncompiled namespace file with a -n
              option.

PMCD-PMDA ERRORS

       These error codes are used in the interactions between pmcd(1) and  the
       PMDAs that provide the performance data.

       PM_ERR_PMDANOTREADY
              PMDA is not yet ready to respond to requests
              Some  PMDAs  have  long  initialization or reset times, and will
              respond to pmcd(1) with this error  if  they  are  busy  at  the
              moment.   This  error  translates  to  PM_ERR_AGAIN  for the PCP
              client who made the request to pmcd  which  caused  the  initial
              request  to  the  PMDA.  At some later time the PMDA will inform
              pmcd (see PM_ERR_PMDAREADY) that it  is  now  ready  to  process
              requests, and client requests will begin to succeed.

       PM_ERR_PMDAREADY
              PMDA is now responsive to requests
              Used by PMDAs to asynchronously inform pmcd(1) that they are now
              willing   to   resume    processing    requests.     See    also
              PM_ERR_PMDANOTREADY.

PCP ENVIRONMENT

       Environment variables with the prefix PCP_ are used to parameterize the
       file and directory names used by PCP.  On each installation,  the  file
       /etc/pcp.conf  contains  the  local  values  for  these variables.  The
       $PCP_CONF variable may be used to specify an alternative  configuration
       file,  as  described in pcp.conf(4).  Values for these variables may be
       obtained programatically using the pmGetConfig(3) function.

SEE ALSO

       pmerr(1),  PMAPI(3),  pmErrStr(3),  pmGetConfig(3),   pcp.conf(4)   and
       pcp.env(4).