# pmsetmode

## NAME



           **pmSetMode** - set collection time and mode parameters for the
           current PMAPI context
    


## C SYNOPSIS



           **#include <pcp/pmapi.h>**
    
           **int pmSetMode(int** _mode_**, const struct timespec ***_when_**,**
                         **const struct timespec ***_delta_**);**
    
           **cc ... -lpcp**
    


## DESCRIPTION



           **pmSetMode** are  used to define the collection time and/or mode for
           accessing performance metrics and metadata in the current  Perfor‐
           mance  Metrics  Application Programming Interface (PMAPI) context.
           This mode affects the semantics of subsequent calls to the follow‐
           ing     PMAPI     routines:     pmFetch(3),     pmFetchArchive(3),
           pmLookupDesc(3),          pmGetInDom(3),         pmLookupInDom(3),
           pmLookupLabels(3) and pmNameInDom(3).
    
           Intended mainly for retrospective analysis of performance  metrics
           from  a PCP archive, the options described below allow an applica‐
           tion to implement seeking to an arbitrary time within the archive,
           playback, fast forward, reverse, etc. by alternating calls to  **pm‐**
           **SetMode** and pmFetch(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**
    
           The other values of _mode_ are used with PCP archives where the  as‐
           sociated 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 val‐
           ues 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 struc‐
           ture returned from a call to  pmGetArchiveLabel(3)  or  the  _start_
           field    in    the    structure    returned   from   a   call   to
           pmGetArchiveLabel(3), and the time at the end of the  archive  can
           be established by calling pmGetArchiveEnd(3)
    
           As  a  special case, if _when_ is **NULL** then the _mode_ and _delta_ argu‐
           ments are used as described below, but the  current  time  in  the
           archive is not altered.
    


## TIME-DRIVEN ARCHIVE MODE



           If _mode_ is **PM_MODE_INTERP** then as metric values are retrieved from
           the  archive  with  pmFetch(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) 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.
    
           When metric values are being requested via pmFetch(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 comput‐
           ed 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  be‐
           fore  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  _Ex‐_
           _plaining_   _Value_   _Interpolation_   _with_   _PCP_  _Archives_  found  at
           **https://pcp.io/papers/archive-interpolation.pdf **.
    


## RECORD-DRIVEN ARCHIVE MODES



           If _mode_ is **PM_MODE_FORW** or **PM_MODE_BACK** then  when  metric  values
           are  being requested via pmFetch(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) 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) 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  inter‐
           vals in the archive the current time may advance by regular inter‐
           vals, 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  encoun‐
           tered,  then  pmFetch(3)  returns  the  special  error  indicator,
           **PM_ERR_EOL**.
    


## RECOMMENDATIONS



           When processing PCP archives, **PM_MODE_INTERP** is preferred because:
    
           • This maximizes the information that will be returned in each
             pmFetch(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 log‐
             ging 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.
    


## EXAMPLES



           To replay interpolated metrics from an archive at 10 second inter‐
           vals, 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 select‐
           ed metrics in an archive in reverse temporal sequence.
    
                struct timespec mytime;
                pmResult result;
    
                pmNewContext(PM_CONTEXT_ARCHIVE, "myarchive");
                pmGetArchiveEnd(&mytime);
                pmSetMode(PM_MODE_BACK, &mytime, NULL);
    
                while (pmFetch(npmid, pmidlist, &result) != PM_ERR_EOL) {
                    /*
                     * process logged metric values as of result->timestamp
                     */
                    . . .
                    pmFreeResult(result);
                }
    


## COMPATIBILITY



           Prior to PCP 7.0 the _when_ argument was a struct timeval and the
           _delta_ argument was an int (in units of milliseconds).  To support
           PMAPI transition, the old interface and semantics can be used if
           applications are recompiled with **-DPMAPI_VERSION=2**.
    
           For a time in PCP 6.x there was a routine with the same semantics
           as the current **pmSetMode** called **pmSetModeHighRes** although this is
           now deprecated and compile-time support for **pmSetModeHighRes** will
           be removed in a future release.
    


## DIAGNOSTICS



           **PM_ERR_MODE**
                  The _mode_ parameter is invalid
    


* * *