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