Provided by: libpcp3-dev_6.0.5-1_amd64 bug

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  archive  logs  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
       archive logs, 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 archive logs 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 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 = 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

       PM_ERR_MODE
              The mode parameter is invalid

SEE ALSO

       PMAPI(3),  pmFetch(3), pmFetchArchive(3), pmGetInDom(3), pmLookupDesc(3), pmLookupInDom(3)
       and pmNameInDom(3).