Section: C Library Functions (3)Updated: SGILocal indexUp
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.
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
viceversa.
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.
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.