NAME
pmFetch - get performance metric values
C SYNOPSIS
#include <pcp/pmapi.h>
int pmFetch(int numpmid, pmID *pmidlist, pmResult
**result)
cc ... -lpcp
DESCRIPTION
Given a list of Performance Metric IDs (PMID)s, e.g. as
constructed by pmLookupName(3), via pmidlist and numpmid,
fetch the values for these performance metrics.
The call to pmFetch is executed in the context of a source
of metrics, instance profile and collection time, previ
ously established by calls to the appropriate context and
profile functions, namely some of pmNewContext(3), pmDup
Context(3), pmUseContext(3), pmAddProfile(3), pmDelPro
file(3) and pmSetMode(3).
The principal result from pmFetch is returned in the argu
ment result as a tree, using the following component data
structures;
typedef struct {
unsigned int vtype : 8; /* value type (same as pmDesc.type) */
unsigned int vlen : 24; /* bytes for vtype/vlen + vbuf */
char vbuf[1]; /* one or more values */
} pmValueBlock;
typedef struct {
int inst; /* instance identifier */
union {
pmValueBlock *pval; /* pointer to value-block */
int lval; /* integer value insitu */
} value;
} pmValue;
typedef struct {
pmID pmid; /* metric identifier */
int numval; /* number of values or error code */
int valfmt; /* value style, insitu or ptr */
pmValue vlist[1]; /* set of instances/values */
} pmValueSet;
/* Result returned by pmFetch() */
typedef struct {
struct timeval timestamp; /* time stamped by collector */
int numpmid; /* number of PMIDs */
} pmResult;
To accommodate metrics with multiple value instances, the
numval field indicates how many values are returned for
each requested PMID. The field valfmt in the pmValueSet
structure indicates if the values for this metric are
stored insitu in the lval field, i.e. a 32-bit integter
quantity (either int, unsigned int, long or unsigned long)
or if the values are held in associated pmValueBlock
structures. The pmValueBlock structure is always used for
floating point values (float or double) and also accommo
dates arbitrary sized binary data such as `string-valued'
metrics and metrics with aggregated or complex data types.
The maximum length of a pmValueBlock buffer is
PM_VAL_VLEN_MAX bytes. If the pmValueBlock format is
used, the vtype field indicates the data type of the
value. This field has the same interpretation as the type
field in the pmDesc structure, see pmLookupDesc(3).
Note that the insitu value may be a signed or unsigned 32
bit integer, signed or unsigned 32 bit long value (on 32
bit platforms), In the special cases described below, it
may also be a 32 bit floating point value. If the appli
cation needs to know the type of an insitu value, which is
almost always the case, it is necessary to fetch the
descriptor for the metric and interpret the type field, as
described in detail in pmLookupDesc(3). When the pmResult
is received from a PCP1.x pmcd, insitu values may also be
32 bit floating point values (of type PM_TYPE_FLOAT). In
all cases, it is good practice to use pmLookupDesc(3) to
fetch the descriptor for the metric and interpret the type
field therein. Note also that the PMAPI(3) will automati
cally translate from the PCP2.0 format to the PCP1.x for
mat when a PCP1.x client requests 32 bit floating point
values from a PCP2.0 pmcd, but the reverse translation
does not occur (because the PCP2.0 pmcd cannot automati
cally distinguish between arbitrary 32 bit floating point
values and 32 bit integers).
If one value (i.e. associated with a particular instance)
for a requested metric is `unavailable' (at the requested
time), then there is no associated pmValue structure in
the result. If there are no available values for a met
ric, then numval will be zero and the associated pmValue[]
instance will be empty (valfmt is undefined in these cir
cumstances, however pmid will be correctly set to the PMID
of the metric with no values).
As an extension of this protocol, if the Performance Met
rics Collection System (PMCS) is able to provide a reason
why no values are available for a particular metric, this
is encoded as a standard error code in the corresponding
numval. Since the error codes are all negative, values
than, or equal to, zero. A performance metric's value may
be `unavailable' for any of the following reasons;
+ The metric is not supported in this version of the
software for the associated Performance Metric Domain
+ Collection is not currently activated in the software
for the associated Performance Metric Domain
+ The associated PMID is not known
+ The current system configuration does not include the
associated hardware component and/or the associated
software module, e.g. a disk is not installed, or off-
line, or Oracle is not installed
+ The metric is one for which an instance profile is
required, and none was provided (there are a small num
ber of metrics in this category, typically ones with
very large, and/or very dynamic instance domains,
and/or expensive metric instantiation methods).
In general, we may not be able to differentiate between
the various cases, and if differentiation is not possible,
numval will simply be zero.
The argument definition and the result specifications have
been constructed to ensure that for each PMID in the
requested pmidlist there is exactly one pmValueSet in the
result, and further the PMIDs appear in exactly the same
sequence in both pmidlist and result. This makes the num
ber and order of entries in result completely determinis
tic, and greatly simplifies the application programming
logic after the call to pmFetch.
The result structure returned by pmFetch is dynamically
allocated using a combination of malloc(3C) calls and spe
cialized allocation strategies, and should be released
when no longer required by calling pmFreeResult(3) - under
no circumstances should free(3C) be called directly to
release this space.
As common error conditions are encoded in the result data
structure, we'd expect only cataclysmic events to cause an
error value to be returned. One example would be if the
metrics source context was a remote host, and that host or
the PMCS on that host became unreachable. Otherwise the
value returned by the pmFetch function will be non-nega
tive.
If the current context involves fetching metrics from a
Performance Metrics Collector Daemon (PMCD), then the
return value may be used to encode out-of-band changes in
rics Daemon Agents (PMDAs), as a bit-wise ``or'' of the
following values:
PMCD_RESTART_AGENT An attempt has been made to restart at
least one failed PMDA.
PMCD_ADD_AGENT At least one PMDA has been started.
PMCD_DROP_AGENT PMCD has noticed the termination of at
least one PMDA.
The default is to return zero to indicate no change in
state, however the pmResult returned by pmFetch has the
same interpretation independent of the return value being
zero or greater than zero.
SEE ALSO
pmcd(1), pmAddProfile(3), PMAPI(3), pmDelProfile(3),
pmDupContext(3), pmExtractValue(3), pmFetchArchive(3),
pmFreeResult(3), pmGetInDom(3), pmLookupDesc(3), pmLookup
Name(3), pmNewContext(3), pmSetMode(3), pmUseContext(3)
and pmWhichContext(3).
Note that pmFetch is the most primitive method of fetching
metric values from the PMCS. More user friendly inter
faces to the PMCS are available or currently under devel
opment - these higher level fetch methods insulate the
user from the intricacies of context creation, setting up
instance profiles, pmResult traversal, and splitting
fetches into batches to minimize PDU traffic or according
to other optimization criteria.
DIAGNOSTICS
As mentioned above, pmFetch returns error codes insitu in
the argument result. If no result is returned, e.g. due
to IPC failure using the current PMAPI context, or end of
file on an archive log, then pmFetch will return a nega
tive error code which may be examined using pmErrStr(3).
PM_ERR_EOL
When fetching records from an archive log, pmFetch
returns this error code to indicate the end of the
log has been passed (or the start of the log has
been passed, if the direction of traversal is back
wards in time). If the ``mode'' for the current
PMAPI context (see pmSetMode(3)) is PM_MODE_INTERP
then the time origin is advanced, even when this
error code is returned. In this way applications
that position the time outside the range defined by
the records in the archive, and then commence to
pmFetch will eventually see valid results once the
time origin moves inside the temporal span of the
archive.
Many of the performance metrics exported from PCP agents
have the semantics of counter meaning they are expected to
be monotonically increasing. Under some circumstances,
one value of these metrics may be smaller than the previ
ously fetched value. This can happen when a counter of
finite precision overflows, or when the PCP agent has been
reset or restarted, or when the PCP agent is exporting
values from some underlying instrumentation that is sub
ject to some asynchronous discontinuity.
The environment variable PCP_COUNTER_WRAP may be set to
indicate that all such cases of a decreasing ``counter''
should be treated as a counter overflow, and hence the
values are assumed to have wrapped once in the interval
between consecutive samples. This ``wrapping'' behavior
was the default in earlier PCP versions, but by default
has been disabled in PCP version 1.3 and later.
Man(1) output converted with
man2html