|
HTML rendering created 2025-02-02 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|
|
NAME | C SYNOPSIS | DESCRIPTION | TIME-DRIVEN ARCHIVE MODE | RECORD-DRIVEN ARCHIVE MODES | RECOMMENDATIONS | EXAMPLES | LARGE DELTA VALUES | DIAGNOSTICS | SEE ALSO | COLOPHON |
|
|
|
PMSETMODE(3) Library Functions Manual PMSETMODE(3)
pmSetMode, pmSetModeHighRes - set collection time and mode
parameters for the current PMAPI context
#include <pcp/pmapi.h>
int pmSetMode(int mode, const struct timeval *when, int delta);
int pmSetModeHighRes(int mode, const struct timespec *when, const struct timespec *delta);
cc ... -lpcp
pmSetMode and pmSetModeHighRes are used to define the collection
time and/or mode for accessing performance metrics and metadata 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),
pmFetchHighRes(3), pmFetchArchive(3), pmLookupDesc(3),
pmGetInDom(3), pmLookupInDom(3), pmLookupLabels(3) and
pmNameInDom(3).
Intended mainly for retrospective analyis of performance metrics
from a PCP archive, the options described below allow an
application to implement seeking to an arbitrary time within the
archive, playback, fast forward, reverse, etc. by alternating
calls to pmSetMode and pmFetch(3) or pmFetchHighRes(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 (when and
delta) are ignored. PM_MODE_LIVE is the default mode when a new
PMAPI context is created with type PM_CONTEXT_HOST (i.e. fetching
metrics from pmcd(1)) or PM_CONTEXT_LOCAL, and this mode is rarely
used in calls to pmSetMode or pmSetModeHighRes.
The other values of mode are used with PCP archives where the
associated PMAPI context must be of type PM_CONTEXT_ARCHIVE (when
it was created with pmNewContext(3)) and the when parameter
defines the current time within the archive. All requests for
metric values and metadata (metric descriptions and instance
identifiers from the instance domains) will be processed to
reflect the state in the archive as of the current time.
When selecting a value for when, the time at the start of the
archive can be established from the ll_start field in the
structure returned from a call to pmGetArchiveLabel(3) or the
start field in the structure returned from a call to
pmGetHighResArchiveLabel(3), and the time at the end of the
archive can be established by calling pmGetArchiveEnd(3) or
pmGetHighResArchiveEnd(3).
As a special case, if when is NULL then the mode and delta
arguments are used as described below, but the current time in the
archive is not altered.
If mode is PM_MODE_INTERP then as metric values are retrieved from
the archive with pmFetch(3) or pmFetchHighRes(3) the current time
is returned as the timestamp in the pmResult structure and the
current time moves on; if delta is positive, the current time
moves forwards, else the current time moves backwards. The
adjustment to the current time is applied even if the pmFetch(3)
or pmFetchHighRes(3) fails to return values for any metrics or
returns an error, e.g. PM_ERR_EOL because the current time is
outside the range defined by the records in the archive.
By default the delta parameter of pmSetMode is interpreted as
milliseconds (but see the LARGE DELTA VALUES section below).
In the pmSetModeHighRes variant of this interface, the delta
parameter is a struct timespec so this can directly represent any
interval.
When metric values are being requested via pmFetch(3) or
pmFetchHighRes(3) the current time may not exactly match the times
at which values have been recorded in the archive, so the returned
metric values are computed from the observed metric values in the
archive (usually at times close to the current time).
For metrics with semantics of PM_SEM_COUNTER, the computed value
is based on linear interpolation between the last observation
before the current time and the first observation after the
current time.
For metrics with semantics of PM_SEM_INSTANT or PM_SEM_DISCRETE,
the computed value is based on values in the neighbourhood of the
current time.
The algorithms used in these computations depend on the semantics
of the metrics and the time series of observed values in the
archive; a fuller explanation may be found in the white paper
Explaining Value Interpolation with PCP Archives found at
https://pcp.io/papers/archive-interpolation.pdf .
If mode is PM_MODE_FORW or PM_MODE_BACK then when metric values
are being requested via pmFetch(3) or pmFetchHighRes(3) the
archive will be scanned in a forwards (PM_MODE_FORW) or backwards
(PM_MODE_BACK) direction in time, until an archive record is
encountered with values for at least one of the requested metrics.
This archive record is used to provide as many of the requested
metrics as possible and these are returned with the timestamp if
the record in the archive, which becomes the new current time.
Note that any metrics requested via pmFetch(3) or
pmFetchHighRes(3) that do not have a value in the archive record
at the new current time will return no values, and so this mode is
most useful for archives where all of the metrics of interest have
been logged regularly at the same time in the archive. Otherwise,
each pmFetch(3) or pmFetchHighRes(3) will contain only the subset
of the requested metrics and any associated instances found in the
qualifying archive record.
The delta parameter is ignored, because the current time is driven
by the timestamp in the matching archive record. So there is no
concept of stepping through the archive in regular time with this
mode, although if the requested metrics appear at regular
intervals in the archive the current time may advance by regular
intervals, but this is serendipitous.
If no qualifying metrics can be found in the requested direction
of searching before the end or start of the archive is
encountered, then pmFetch(3) or pmFetchHighRes(3) returns the
special error indicator, PM_ERR_EOL.
When processing PCP archives, PM_MODE_INTERP is preferred because:
• This maximizes the information that will be returned in each
pmFetch(3) or pmFetchHighRes(3).
• This returns values at regular intervals of the current time,
independent of the logging frequency for requested metrics in
the archive.
• This works with any PCP archive, as opposed to the record-driven
modes which may work acceptably for archives with regular
logging of all requested metrics, but may fail to report
complete or useful results for other archives.
• This mode provides the closest semantic match to PM_MODE_LIVE
and leads to the least user surprise when moving between real-
time monitoring and retrospective analysis.
To replay interpolated metrics from an archive at 10 second
intervals, the following code fragment could be used:
struct timeval mytime;
int mydelta = 10 * 1000; /* msec */
pmLogLabel label;
pmResult result;
pmNewContext(PM_CONTEXT_ARCHIVE, "myarchive");
pmGetArchiveLabel(&label);
mytime = label.ll_start;
pmSetMode(PM_MODE_INTERP, &mytime, mydelta)
while (pmFetch(numpmid, pmidlist, &result) != PM_ERR_EOL) {
/*
* process interpolated metric values as of
* result->timestamp
*/
. . .
pmFreeResult(result);
}
The following code fragment may be used to dump values for
selected metrics in an archive in reverse temporal sequence.
struct timeval mytime;
pmResult result;
pmNewContext(PM_CONTEXT_ARCHIVE, "myarchive");
pmGetArchiveEnd(&mytime);
pmSetMode(PM_MODE_BACK, &mytime, 0);
while (pmFetch(npmid, pmidlist, &result) != PM_ERR_EOL) {
/*
* process logged metric values as of result->timestamp
*/
. . .
pmFreeResult(result);
}
The simplest mechanism to set large values for delta is to use the
pmSetModeHighRes interface. However, the pmSetMode interface
supports the XTB (eXtended Time Base) mechanism to allow for
values in units other than milliseconds.
Because the delta parameter to pmSetMode is an int and treated as
milliseconds by default there is a limit on the maximum absolute
value of delta that can be specified with this default
interpretation, namely about 24 days if a signed int has 31 bits
of precision. To accommodate longer values of delta the high-
order bits of the mode parameter is also used to optionally set
the units of time for the delta parameter. To specify the units of
time use the PM_XTB_SET macro with one of the values PM_TIME_NSEC,
PM_TIME_MSEC, PM_TIME_SEC, etc. to set the mode as follows:
PM_MODE_INTERP | PM_XTB_SET(PM_TIME_XXXX)
The following code shows how this could be done if the desired
delta is initially encoded in interval (a struct timeval).
struct timeval interval;
int mode;
mode = ...
if (abs(interval.tv_sec / (3600*24)) <= 24) {
/* default encoding of milliseconds is fine */
mode = PM_MODE_INTERP;
delta = interval.tv_sec * 1000 + (interval.tv_usec + 500)/ 1000;
}
else {
/* encode delta in units of seconds */
mode = PM_MODE_INTERP | PM_XTB_SET(PM_TIME_SEC);
delta = interval.tv_sec + (interval.tv_usec + 500000)/ 1000000;
}
For millisecond encoding of delta, using PM_XTB_SET(PM_TIME_MSEC)
is functionally equivalent to not using PM_XTB_SET at all.
PM_ERR_MODE
The mode parameter is invalid
pmcd(1), PMAPI(3), pmFetch(3), pmFetchArchive(3),
pmFetchHighRes(3), pmGetArchiveEnd(3), pmGetArchiveLabel(3),
pmGetHighResArchiveEnd(3), pmGetHighResArchiveLabel(3),
pmGetInDom(3), pmLookupDesc(3), pmLookupInDom(3),
pmLookupLabels(3), pmNameInDom(3) and pmNewContext(3).
This page is part of the PCP (Performance Co-Pilot) project.
Information about the project can be found at
⟨http://www.pcp.io/⟩. If you have a bug report for this manual
page, send it to pcp@groups.io. This page was obtained from the
project's upstream Git repository
⟨https://github.com/performancecopilot/pcp.git⟩ on 2025-02-02.
(At that time, the date of the most recent commit that was found
in the repository was 2025-01-30.) If you discover any rendering
problems in this HTML version of the page, or you believe there is
a better or more up-to-date source for the page, or you have
corrections or improvements to the information in this COLOPHON
(which is not part of the original manual page), send a mail to
man-pages@man7.org
Performance Co-Pilot PCP PMSETMODE(3)
Pages that refer to this page: pcpintro(1), pcpintro(3), pmapi(3), pmfetch(3), pmfetcharchive(3), pmfetchgroup(3), pmgetarchiveend(3), pmnewcontext(3), pmstore(3), pmtime(3), QmcGroup(3)
|
HTML rendering created 2025-02-02 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|