NAME¶
pmSetMode - set collection time parameters for the current PMAPI context
C SYNOPSIS¶
#include <pcp/pmapi.h>
int pmSetMode(int
mode, const struct timeval *
when, int
delta);
cc ... -lpcp
DESCRIPTION¶
pmSetMode is used to define the collection time and/or mode for accessing
performance metrics and meta-data in the current Performance Metrics
Application Programming Interface (PMAPI) context. This mode affects the
semantics of subsequent calls to the following PMAPI routines:
pmFetch(3),
pmFetchArchive(3),
pmLookupDesc(3),
pmGetInDom(3),
pmLookupInDom(3) and
pmNameInDom(3).
If
mode is
PM_MODE_LIVE then all information is returned from the
active pool of performance metrics as of the time that the PMAPI call is made,
and the other two parameters to
pmSetMode are ignored.
PM_MODE_LIVE is the default mode when a new PMAPI context of type
PM_CONTEXT_HOST is created.
If the
mode is not
PM_MODE_LIVE, then the
when parameter
defines a time origin, and all requests for meta-data (metric descriptions and
instance identifiers from the instance domains) will be processed to reflect
the state of the meta-data as of the time origin, i.e. we use the last state
of this information at, or before, the time origin.
If the
mode is
PM_MODE_INTERP then, in the case of
pmFetch(3), the underlying code will use an interpolation scheme to
compute the values of the metrics from the values recorded for times in the
proximity of the time origin. A
mode of
PM_MODE_INTERP may only
be used with an archive context.
If the
mode is
PM_MODE_FORW then, in the case of
pmFetch(3), the collection of recorded metric values will be scanned in
a forwards direction in time, until values for at least one of the requested
metrics is located after the time origin, and then all requested metrics
stored in the log or archive at that time will be returned with the
corresponding timestamp. A
mode of
PM_MODE_FORW may only be used
with an archive context.
If the
mode is
PM_MODE_BACK then, the situation is the same as for
PM_MODE_FORW, except a
pmFetch(3) will be serviced by scanning
the collection of recorded metrics in a backwards direction in time for
metrics before the time origin. A
mode of
PM_MODE_BACK may only
be used with an archive context.
If the
mode is
PM_MODE_FORW or
PM_MODE_BACK, and no
qualifying metrics can be found in the requested direction of searching before
the end or start of the archive log is found, then
pmFetch(3) returns
the special error indicator,
PM_ERR_EOL.
For
modes other than
PM_MODE_LIVE, after each successful
pmFetch(3), the time origin is reset to the timestamp returned via the
pmResult structure from
pmFetch(3).
The
pmSetMode parameter
delta defines an additional number of time
units that should be used to adjust the time origin (forwards or backwards),
after the new time origin from the
pmResult has been determined. This
automatic adjustment of the time origin only occurs when the
mode is
PM_MODE_INTERP, and the adjustment is applied, even if the
pmFetch(3) fails because the time origin is outside the range defined
by the records in an archive log, i.e. returns
PM_ERR_EOL. The
high-order bits of the
mode parameter is also used to optionally set
the units of time for the
delta field. To specify the units of time use
PM_XTB_SET macro with one of the values
PM_TIME_NSEC,
PM_TIME_MSEC,
PM_TIME_SEC, etc. as follows:
PM_MODE_INTERP | PM_XTB_SET(PM_TIME_XXXX)
If no units are specified the default is to interpret
delta as
milliseconds.
Using these
mode options, an application can implement replay, playback,
fast forward, reverse, etc. for performance metric values held in the archive
log by alternating calls to
pmSetMode and
pmFetch(3).
As a special case, if
when is
NULL then the
mode and
delta arguments are used as described above, but the current time in
the archive is not altered.
For example, the following code fragment may be used to dump just those values
recorded in an archive in correct temporal sequence, for a selected set of
performance metrics; this uses the default collection time mechanisms.
pmNewContext(PM_CONTEXT_ARCHIVE, "myarchive");
while (pmFetch(npmid, pmidlist, &result) != PM_ERR_EOL) {
/*
* process real metric values as of result->timestamp
*/
. . .
pmFreeResult(result);
}
Alternatively, to replay interpolated metrics from the log in reverse
chronological order, at 10 second intervals (of recorded time), the following
code fragment could be used.
struct timeval mytime;
mytime.tv_sec = 0x7fffffff;
pmSetMode(PM_MODE_BACK, &mytime, 0);
pmFetchArchive(&result);
mytime = result->timestamp;
pmFreeResult(result);
pmSetMode(PM_MODE_INTERP | PM_XTB_SET(PM_TIME_SEC), &mytime, -10);
while (pmFetch(numpmid, pmidlist, &result) != PM_ERR_EOL) {
/*
* process interpolated metric values as of
* result->timestamp
*/
. . .
pmFreeResult(result);
}
SEE ALSO¶
PMAPI(3),
pmFetch(3),
pmFetchArchive(3),
pmGetInDom(3),
pmLookupDesc(3),
pmLookupInDom(3) and
pmNameInDom(3).
DIAGNOSTICS¶
- PM_ERR_MODE
- The mode parameter is invalid