1PMSETMODE(3) Library Functions Manual PMSETMODE(3)
2
6 pmSetMode - set collection time parameters for the current PMAPI con‐
7 text
8
10 #include <pcp/pmapi.h>
11 int pmSetMode(int mode, const struct timeval *when, int delta);
13 cc ... -lpcp
15
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 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 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 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 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 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 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 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 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 By default delta is interpreted as milliseconds (but see the LARGE
74 DELTA VALUES section below).
75 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 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
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 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 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 struct timeval mytime;
105 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 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
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 PM_MODE_INTERP | PM_XTB_SET(PM_TIME_XXXX)
133 The following code shows how this could be done if the desired delta is
135 initially encoded in interval (a struct timeval).
136 struct timeval interval;
138 int mode;
139 mode = ...
141 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 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
157 PMAPI(3), pmFetch(3), pmFetchArchive(3), pmGetInDom(3),
158 pmLookupDesc(3), pmLookupInDom(3) and pmNameInDom(3).
159
161 PM_ERR_MODE
162 The mode parameter is invalid
163Performance Co-Pilot PCP PMSETMODE(3)