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

           uations.

       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 connect­
           ing  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

           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  specifica­
           tions of the source and destination units.

       PM_ERR_PROFILE
           Explicit instance identifier(s) required
           Some  PMDAs, especially the proc PMDA, will not return

           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  pmAddPro­
           file(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_CON­
           TEXT_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), pmLookup­
           Name(3) or pmStore(3).

       PM_ERR_TOOBIG
           Result size exceeded
           Indicates a fatal error in the message (or PDU)  pass­
           ing 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.

           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  pos­
           sible.


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 pmLookupIn­
              Dom(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 appli­
              cation  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  con­
              trolled   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 responsi­
              ble  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 pmlog­
              ger(1).  This error occurs when an unauthorized PCP
              client  attempts  to  connect  to   an   unlicensed
              pmcd(1).

              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 met­
              rics
              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  termina­
              tion  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.

              Metric not defined in the PCP archive log
              A PCP client has requested information about a met­
              ric, 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  met­
              rics,  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 spe­
              cific  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

              control routines pmTime*(3) when not currently con­
              nected 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 a
              null.

       PM_ERR_WANTACK
              Cannot send due to pending acknowledgements
              Some client of pmtime(1) is not acknowledging  mes­
              sages  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 avail­
       able 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 ille­
              gal to call either of pmLoadNameSpace(3) or pmLoad­
              ASCIINameSpace(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  pmn­
              scomp(1) and client applications that use an uncom­
              piled 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 pmn­
              scomp(1) and client applications that use an uncom­
              piled 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

              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).


Man(1) output converted with man2html