Ubuntu Manpage: pmSetMode, pmSetModeHighRes - set collection time parameters for the current PMAPI context

Provided by: libpcp3-dev_6.2.0-1.1build4_amd64

NAME

       pmSetMode, pmSetModeHighRes - 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);
       int pmSetModeHighRes(int mode, const struct timespec *when, const struct timespec *delta);

       cc ... -lpcp

DESCRIPTION

pmSetMode and pmSetModeHighRes are 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 set of archives 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 set of archives 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 a set of archives, i.e. returns PM_ERR_EOL.

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 can
directly represent any interval.

Using these mode options, an application can implement replay, playback, fast forward, reverse, etc. for
performance metric values held in the set of archives 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.

EXAMPLES

       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 archive in  reverse  chronological  order,  at  10
       second intervals (of recorded time), the following code fragment could be used.

            struct timeval mytime;

            mytime.tv_sec = PM_MAX_TIME_T; /* or use pmGetArchiveEnd(&mtime) */
            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);
            }

       To perform the same operations, using high resolution time:

            struct timespec mytime, mydelta = { -10, 0 };

            mytime.tv_sec = PM_MAX_TIME_T; /* or use pmGetHighResArchiveEnd(&mtime) */
            pmSetModeHighRes(PM_MODE_BACK, &mytime, NULL);
            pmFetchHighResArchive(&result);
            mytime = result->timestamp;
            pmFreeHighResResult(result);
            pmSetModeHighRes(PM_MODE_INTERP, &mytime, &mydelta);

            while (pmFetchHighRes(numpmid, pmidlist, &result) != PM_ERR_EOL) {
                /*
                 * process interpolated metric values as of
                 * result->timestamp
                 */
                . . .
                pmFreeHighResResult(result);
            }

LARGE DELTA VALUES

       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.

DIAGNOSTICS