pmsetmode(3) — Linux manual page

NAME | C SYNOPSIS | DESCRIPTION | TIME-DRIVEN ARCHIVE MODE | RECORD-DRIVEN ARCHIVE MODES | RECOMMENDATIONS | EXAMPLES | COMPATIBILITY | DIAGNOSTICS | SEE ALSO | COLOPHON

PMSETMODE(3)             Library Functions Manual            PMSETMODE(3)

NAME         top

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

C SYNOPSIS         top

       #include <pcp/pmapi.h>

       int pmSetMode(int mode, const struct timespec *when,
                     const struct timespec *delta);

       cc ... -lpcp

DESCRIPTION         top

       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         top

       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         top

       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         top

       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         top

       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         top

       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         top

       PM_ERR_MODE
              The mode parameter is invalid

SEE ALSO         top

       pmcd(1), PMAPI(3), pmFetch(3), pmFetchArchive(3),
       pmGetArchiveEnd(3), pmGetArchiveLabel(3), pmGetInDom(3),
       pmLookupDesc(3), pmLookupInDom(3), pmLookupLabels(3),
       pmNameInDom(3) and pmNewContext(3).

COLOPHON         top

       This page is part of the PCP (Performance Co-Pilot) project.  In‐
       formation 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-08-11.  (At that time, the date of the most recent commit
       that was found in the repository was 2025-08-11.)  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)