pmsetmode(3)

1PMSETMODE(3)               Library Functions Manual               PMSETMODE(3)
2
3
4

NAME

6       pmSetMode  -  set collection time parameters for the current PMAPI con‐
7       text
8

C SYNOPSIS

10       #include <pcp/pmapi.h>
11
12       int pmSetMode(int mode, const struct timeval *when, int delta);
13
14       cc ... -lpcp
15

DESCRIPTION

17       pmSetMode is used to define the collection time and/or mode for access‐
18       ing  performance  metrics and meta-data in the current Performance Met‐
19       rics Application Programming  Interface  (PMAPI)  context.   This  mode
20       affects  the  semantics of subsequent calls to the following PMAPI rou‐
21       tines: pmFetch(3), pmFetchArchive(3),  pmLookupDesc(3),  pmGetInDom(3),
22       pmLookupInDom(3) and pmNameInDom(3).
23
24       If  mode  is  PM_MODE_LIVE  then  all  information is returned from the
25       active pool of performance metrics as of the time that the  PMAPI  call
26       is  made,  and  the  other  two  parameters  to  pmSetMode are ignored.
27       PM_MODE_LIVE is the default mode when  a  new  PMAPI  context  of  type
28       PM_CONTEXT_HOST is created.
29
30       If the mode is not PM_MODE_LIVE, then the when parameter defines a time
31       origin,  and  all  requests  for  meta-data  (metric  descriptions  and
32       instance  identifiers  from  the instance domains) will be processed to
33       reflect the state of the meta-data as of the time origin, i.e.  we  use
34       the last state of this information at, or before, the time origin.
35
36       If  the  mode  is  PM_MODE_INTERP  then, in the case of pmFetch(3), the
37       underlying code will use an interpolation scheme to compute the  values
38       of  the  metrics from the values recorded for times in the proximity of
39       the time origin.  A mode of PM_MODE_INTERP may only be used with an ar‐
40       chive context.
41
42       If  the  mode is PM_MODE_FORW then, in the case of pmFetch(3), the col‐
43       lection of recorded metric values will be scanned in a forwards  direc‐
44       tion in time, until values for at least one of the requested metrics is
45       located after the time origin, and then all requested metrics stored in
46       the  set of archives at that time will be returned with the correspond‐
47       ing timestamp.  A mode of PM_MODE_FORW may only be used with an archive
48       context.
49
50       If  the  mode  is  PM_MODE_BACK  then, the situation is the same as for
51       PM_MODE_FORW, except a pmFetch(3) will be serviced by scanning the col‐
52       lection  of  recorded metrics in a backwards direction in time for met‐
53       rics before the time origin.  A mode of PM_MODE_BACK may only  be  used
54       with an archive context.
55
56       If  the mode is PM_MODE_FORW or PM_MODE_BACK, and no qualifying metrics
57       can be found in the requested direction of searching before the end  or
58       start  of the set of archive logs is found, then pmFetch(3) returns the
59       special error indicator, PM_ERR_EOL.
60
61       For modes other than PM_MODE_LIVE, after  each  successful  pmFetch(3),
62       the  time  origin  is  reset to the timestamp returned via the pmResult
63       structure from pmFetch(3).
64
65       The pmSetMode parameter delta defines  an  additional  number  of  time
66       units  that should be used to adjust the time origin (forwards or back‐
67       wards), after the new time origin from the  pmResult  has  been  deter‐
68       mined.   This  automatic adjustment of the time origin only occurs when
69       the mode is PM_MODE_INTERP, and the adjustment is applied, even if  the
70       pmFetch(3)  fails  because the time origin is outside the range defined
71       by the records in a set of archive logs, i.e. returns PM_ERR_EOL.
72
73       By default delta is interpreted as  milliseconds  (but  see  the  LARGE
74       DELTA VALUES section below).
75
76       Using  these  mode  options, an application can implement replay, play‐
77       back, fast forward, reverse, etc. for performance metric values held in
78       the  set  of  archive  logs  by  alternating  calls  to  pmSetMode  and
79       pmFetch(3).
80
81       As a special case, if when is NULL then the mode  and  delta  arguments
82       are used as described above, but the current time in the archive is not
83       altered.
84

EXAMPLES

86       The following code fragment may be  used  to  dump  just  those  values
87       recorded in an archive in correct temporal sequence, for a selected set
88       of performance metrics; this uses the default  collection  time  mecha‐
89       nisms.
90
91            pmNewContext(PM_CONTEXT_ARCHIVE, "myarchive");
92            while (pmFetch(npmid, pmidlist, &result) != PM_ERR_EOL) {
93                /*
94                 * process real metric values as of result->timestamp
95                 */
96                . . .
97                pmFreeResult(result);
98            }
99
100       Alternatively,  to  replay interpolated metrics from the log in reverse
101       chronological order, at 10 second intervals  (of  recorded  time),  the
102       following code fragment could be used.
103
104            struct timeval mytime;
105
106            mytime.tv_sec = 0x7fffffff; /* or use pmGetArchiveEnd(&mtime) */
107            pmSetMode(PM_MODE_BACK, &mytime, 0);
108            pmFetchArchive(&result);
109            mytime = result->timestamp;
110            pmFreeResult(result);
111            pmSetMode(PM_MODE_INTERP | PM_XTB_SET(PM_TIME_SEC), &mytime, -10);
112
113            while (pmFetch(numpmid, pmidlist, &result) != PM_ERR_EOL) {
114                /*
115                 * process interpolated metric values as of
116                 * result->timestamp
117                 */
118                . . .
119                pmFreeResult(result);
120            }
121

LARGE DELTA VALUES

123       Because delta is an int and treated as milliseconds by default there is
124       a limit on the maximum absolute value of delta that  can  be  specified
125       with  this default interpretation, namely about 24 days if a signed int
126       has 31 bits of precision.  To accommodate longer values  of  delta  the
127       high-order  bits  of  the mode parameter is also used to optionally set
128       the units of time for the delta parameter. To specify the units of time
129       use   the  PM_XTB_SET  macro  with  one  of  the  values  PM_TIME_NSEC,
130       PM_TIME_MSEC, PM_TIME_SEC, etc.  to set the mode as follows:
131
132            PM_MODE_INTERP | PM_XTB_SET(PM_TIME_XXXX)
133
134       The following code shows how this could be done if the desired delta is
135       initially encoded in interval (a struct timeval).
136
137            struct timeval interval;
138            int mode;
139
140            mode = ...
141
142            if (abs(interval.tv_sec / (3600*24)) <= 24) {
143                /* default encoding of milliseconds is fine */
144                mode = PM_MODE_INTERP;
145                delta = interval.tv_sec * 1000 + (interval.tv_usec + 500)/ 1000;
146            }
147            else {
148                /* encode delta in units of seconds */
149                mode = PM_MODE_INTERP | PM_XTB_SET(PM_TIME_SEC);
150                delta = interval.tv_sec + (interval.tv_usec + 500000)/ 1000000;
151            }
152
153       For  millisecond  encoding  of delta, using PM_XTB_SET(PM_TIME_MSEC) is
154       functionally equivalent to not using PM_XTB_SET at all.
155

DIAGNOSTICS

161       PM_ERR_MODE
162              The mode parameter is invalid
163
164
165
166Performance Co-Pilot                  PCP                         PMSETMODE(3)

NAME

C SYNOPSIS

DESCRIPTION

EXAMPLES

LARGE DELTA VALUES

SEE ALSO

DIAGNOSTICS