# pcpintro

## NAME



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


## INTRODUCTION



           Performance Co-Pilot (PCP) is a toolkit 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_IPC**
               _IPC protocol failure_
               Generic protocol failure on a pipe or socket connecting two
               PCP applications, e.g. client-**pmcd** , or client-**pmtime** , or
               PMDA-**pmcd** or **pmlc** -**pmlogger**.
    
           **PM_ERR_TEXT**
               _One-line 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, e.g.
    
               (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 set of PCP archives.
    
               (c) A bad _result_ data structure passed to pmStore(3).
    
           **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, e.g. 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, e.g. bad debug
               flag symbolic name for **-D/--debug** 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_TYPE**
               _Unknown or illegal metric type_
               The metric type is held in the metric descriptor and sometimes
               encoded in the metric values returned from a call to
               pmFetch(3).  Legal values for the metric type are defined by
               the **PM_TYPE_*** macros in **< pcp/pmapi.h>**.
    
           **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/--fetchall** option to pminfo(1).
    
           **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_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_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_FAULT**
               _QA fault injected_
               For testing, there is a ``fault injection'' version of **libpcp**
               and this error indicates a misuse of the fault injection
               infrastructure.
    
           **PM_ERR_THREAD**
               _Operation not supported for multi-threaded applications_
               As documented in PMAPI(3) and elsewhere, some **libpcp** routines
               are intended solely for use from single-threaded applications.
    
           **PM_ERR_NOCONTAINER**
               _Container not found_ The user supplied container name does not
               match any known container.
    
           **PM_ERR_BADSTORE**
               _Bad input to pmstore_
               The metric value provided for a pmStore(3) operation is in the
               wrong format, or of the wrong type or has the wrong number of
               values.
    
           **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_FAULT**
               _QA fault injected_
               Used only for PCP Quality Assurance (QA) testing.
    
           **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.
    
           **PM_ERR_BADDERIVE**
               _Derived metric definition failed_
               When registering a derived metric, the metric expression is
               either syntactically or semantically incorrect.
    
           **PM_ERR_NOLABELS**
               _No support for metric label metadata_
               Operation requires metric labels, but none are available.
    


## CLIENT-PMCD ERRORS



           These errors may occur in the interactions between a PCP client
           and pmcd(1) providing real-time performance data.
    
           **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_NOPROFILE**
                  _Missing profile - protocol botch_
                  Internal error in the communication between a client
                  application and pmcd(1) - should not occur.
    
           **PM_ERR_NEEDCLIENTCERT**
                  _PMCD requires a client certificate_ Authentication failure.
    
           **PM_ERR_PMDAFENCED**
                  _PMDA is currently fenced and unable to respond to requests_
                  A privileged user has decided to isolate a PMDA from
                  pmcd(1) using a pmStore(1) operation on the
                  **pmcd.agent.fenced** metric, which means all fetch-level
                  requests to that PMDA are being blocked.
    


## 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_LOGFILE**
                  _Missing archive file_
                  Each PCP archive consists of multiple physical files as
                  described in pmlogger(1).  This error occurs when one of
                  the physical files is missing or cannot be opened for
                  reading.
    
           **PM_ERR_EOL**
                  _End of PCP archive_
                  An attempt is made to read past the end file of the last
                  volume of a set of PCP archives, or past the end of the
                  time window (as specified with a **-T/--finish** option) for a
                  set of PCP archives.
    
           **PM_ERR_NOTHOST**
                  _Operation requires context with host source of metrics_
                  Calls to pmStore(3) require a host context and are not
                  supported for PCP archives.
    
                  For archives created with versions of PCP prior to 4.0, the
                  pmLookupText(3) and pmLookupInDomText(3) calls will return
                  this code for archive PMAPI contexts (help and one-line
                  text was not previously recorded in archives).
    
           **PM_ERR_LOGREC**
                  _Corrupted record in a PCP archive_
                  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 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 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 set of PCP
                  archives.
    
           **PM_ERR_PMID_LOG**
                  _Metric not defined in the PCP archive_
                  A PCP client has requested information about a metric, and
                  there is no corresponding information in the set of PCP
                  archives.  This should not happen for well-behaved PCP
                  clients.
    
           **PM_ERR_INDOM_LOG**
                  _Instance domain identifier not defined in the PCP archive_
                  A PCP client has requested information about an instance
                  domain for one or more performance metrics, and there is no
                  corresponding information in the set of PCP archives.  If
                  the client is using metric descriptors from the set of
                  archives 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_
                  A PCP client has requested information about a specific
                  instance of a performance metric, and there is no
                  corresponding information in the set of PCP archives.  If
                  the client is using instance names from the instance domain
                  in the set of archives (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.
    
           **PM_ERR_LOGOVERLAP**
                  _Archives overlap in time_
                  When using a context associated with a set of archives, the
                  archives in the set may not overlap in time.
    
           **PM_ERR_LOGHOST**
                  _Archives differ by host_
                  When using a context associated with a set of archives, the
                  archives in the set must all have been generated on the
                  same host.
    
           **PM_ERR_LOGCHANGETYPE**
                  _The type of a metric differs among archives_
                  When using a context associated with a set of archives, the
                  type of each metric must be same in all of the archives.
    
           **PM_ERR_LOGCHANGESEM**
                  _The semantics of a metric differs among archives_
                  When using a context associated with a set of archives, the
                  semantics of each metric must be same in all of the
                  archives.
    
           **PM_ERR_LOGCHANGEINDOM**
                  _The instance domain of a metric differs among archives_
                  When using a context associated with a set of archives, the
                  instance domain of each metric must be same in all of the
                  archives.
    
           **PM_ERR_LOGCHANGEUNITS**
                  _The units of a metric differs among archives_
                  When using a context associated with a set of archives, the
                  units of each metric must be same in all of the archives.
    


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


## NAMESPACE ERRORS



           These errors may occur in the processing of PCP namespace
           operations.  A PCP namespace, see PMNS(5), 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 explicitly loaded.
    
           **PM_ERR_NOPMNS**
                  _PMNS not accessible_
                  Only occurs when an ASCII namespace is explicitly loaded.
    


## 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(5).
           Values for these variables may be obtained programmatically using
           the pmGetConfig(3) function.
    


* * *