Man Linux: Main Page and Category List

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