1PMSETMODE(3) Library Functions Manual PMSETMODE(3)
2
6 pmSetMode, pmSetModeHighRes - set collection time parameters for the
7 current PMAPI context
8
10 #include <pcp/pmapi.h>
11 int pmSetMode(int mode, const struct timeval *when, int delta);
13 int pmSetModeHighRes(int mode, const struct timespec *when, const struct timespec *delta);
14 cc ... -lpcp
16
18 pmSetMode and pmSetModeHighRes are used to define the collection time
19 and/or mode for accessing performance metrics and meta-data in the cur‐
20 rent Performance Metrics Application Programming Interface (PMAPI) con‐
21 text. This mode affects the semantics of subsequent calls to the fol‐
22 lowing PMAPI routines: pmFetch(3), pmFetchArchive(3), pmLookupDesc(3),
23 pmGetInDom(3), pmLookupInDom(3) and pmNameInDom(3).
24 If mode is PM_MODE_LIVE then all information is returned from the ac‐
26 tive pool of performance metrics as of the time that the PMAPI call is
27 made, and the other two parameters to pmSetMode are ignored.
28 PM_MODE_LIVE is the default mode when a new PMAPI context of type
29 PM_CONTEXT_HOST is created.
30 If the mode is not PM_MODE_LIVE, then the when parameter defines a time
32 origin, and all requests for meta-data (metric descriptions and in‐
33 stance identifiers from the instance domains) will be processed to re‐
34 flect the state of the meta-data as of the time origin, i.e. we use the
35 last state of this information at, or before, the time origin.
36 If the mode is PM_MODE_INTERP then, in the case of pmFetch(3), the un‐
38 derlying code will use an interpolation scheme to compute the values of
39 the metrics from the values recorded for times in the proximity of the
40 time origin. A mode of PM_MODE_INTERP may only be used with an archive
41 context.
42 If the mode is PM_MODE_FORW then, in the case of pmFetch(3), the col‐
44 lection of recorded metric values will be scanned in a forwards direc‐
45 tion in time, until values for at least one of the requested metrics is
46 located after the time origin, and then all requested metrics stored in
47 the set of archives at that time will be returned with the correspond‐
48 ing timestamp. A mode of PM_MODE_FORW may only be used with an archive
49 context.
50 If the mode is PM_MODE_BACK then, the situation is the same as for
52 PM_MODE_FORW, except a pmFetch(3) will be serviced by scanning the col‐
53 lection of recorded metrics in a backwards direction in time for met‐
54 rics before the time origin. A mode of PM_MODE_BACK may only be used
55 with an archive context.
56 If the mode is PM_MODE_FORW or PM_MODE_BACK, and no qualifying metrics
58 can be found in the requested direction of searching before the end or
59 start of the set of archive logs is found, then pmFetch(3) returns the
60 special error indicator, PM_ERR_EOL.
61 For modes other than PM_MODE_LIVE, after each successful pmFetch(3),
63 the time origin is reset to the timestamp returned via the pmResult
64 structure from pmFetch(3).
65 The pmSetMode parameter delta defines an additional number of time
67 units that should be used to adjust the time origin (forwards or back‐
68 wards), after the new time origin from the pmResult has been deter‐
69 mined. This automatic adjustment of the time origin only occurs when
70 the mode is PM_MODE_INTERP, and the adjustment is applied, even if the
71 pmFetch(3) fails because the time origin is outside the range defined
72 by the records in a set of archive logs, i.e. returns PM_ERR_EOL.
73 By default the delta parameter of pmSetMode is interpreted as millisec‐
75 onds (but see the LARGE DELTA VALUES section below).
76 In the pmSetModeHighRes variant of this interface, the delta parameter
78 is a struct timespec so can directly represent any interval.
79 Using these mode options, an application can implement replay, play‐
81 back, fast forward, reverse, etc. for performance metric values held in
82 the set of archive logs by alternating calls to pmSetMode and pm‐
83 Fetch(3).
84 As a special case, if when is NULL then the mode and delta arguments
86 are used as described above, but the current time in the archive is not
87 altered.
88
90 The following code fragment may be used to dump just those values
91 recorded in an archive in correct temporal sequence, for a selected set
92 of performance metrics; this uses the default collection time mecha‐
93 nisms.
94 pmNewContext(PM_CONTEXT_ARCHIVE, "myarchive");
96 while (pmFetch(npmid, pmidlist, &result) != PM_ERR_EOL) {
97 /*
98 * process real metric values as of result->timestamp
99 */
100 . . .
101 pmFreeResult(result);
102 }
103 Alternatively, to replay interpolated metrics from the log in reverse
105 chronological order, at 10 second intervals (of recorded time), the
106 following code fragment could be used.
107 struct timeval mytime;
109 mytime.tv_sec = PM_MAX_TIME_T; /* or use pmGetArchiveEnd(&mtime) */
111 pmSetMode(PM_MODE_BACK, &mytime, 0);
112 pmFetchArchive(&result);
113 mytime = result->timestamp;
114 pmFreeResult(result);
115 pmSetMode(PM_MODE_INTERP | PM_XTB_SET(PM_TIME_SEC), &mytime, -10);
116 while (pmFetch(numpmid, pmidlist, &result) != PM_ERR_EOL) {
118 /*
119 * process interpolated metric values as of
120 * result->timestamp
121 */
122 . . .
123 pmFreeResult(result);
124 }
125 To perform the same operations, using high resolution time:
127 struct timespec mytime, mydelta = { -10, 0 };
129 mytime.tv_sec = PM_MAX_TIME_T; /* or use pmGetHighResArchiveEnd(&mtime) */
131 pmSetModeHighRes(PM_MODE_BACK, &mytime, NULL);
132 pmFetchHighResArchive(&result);
133 mytime = result->timestamp;
134 pmFreeHighResResult(result);
135 pmSetModeHighRes(PM_MODE_INTERP, &mytime, &mydelta);
136 while (pmFetchHighRes(numpmid, pmidlist, &result) != PM_ERR_EOL) {
138 /*
139 * process interpolated metric values as of
140 * result->timestamp
141 */
142 . . .
143 pmFreeHighResResult(result);
144 }
145
147 The simplest mechanism to set large values for delta is to use the pm‐
148 SetModeHighRes interface. However, the pmSetMode interface supports
149 the XTB (eXtended Time Base) mechanism to allow for values in units
150 other than milliseconds.
151 Because the delta parameter to pmSetMode is an int and treated as mil‐
153 liseconds by default there is a limit on the maximum absolute value of
154 delta that can be specified with this default interpretation, namely
155 about 24 days if a signed int has 31 bits of precision. To accommodate
156 longer values of delta the high-order bits of the mode parameter is
157 also used to optionally set the units of time for the delta parameter.
158 To specify the units of time use the PM_XTB_SET macro with one of the
159 values PM_TIME_NSEC, PM_TIME_MSEC, PM_TIME_SEC, etc. to set the mode
160 as follows:
161 PM_MODE_INTERP | PM_XTB_SET(PM_TIME_XXXX)
163 The following code shows how this could be done if the desired delta is
165 initially encoded in interval (a struct timeval).
166 struct timeval interval;
168 int mode;
169 mode = ...
171 if (abs(interval.tv_sec / (3600*24)) <= 24) {
173 /* default encoding of milliseconds is fine */
174 mode = PM_MODE_INTERP;
175 delta = interval.tv_sec * 1000 + (interval.tv_usec + 500)/ 1000;
176 }
177 else {
178 /* encode delta in units of seconds */
179 mode = PM_MODE_INTERP | PM_XTB_SET(PM_TIME_SEC);
180 delta = interval.tv_sec + (interval.tv_usec + 500000)/ 1000000;
181 }
182 For millisecond encoding of delta, using PM_XTB_SET(PM_TIME_MSEC) is
184 functionally equivalent to not using PM_XTB_SET at all.
185
187 PM_ERR_MODE
188 The mode parameter is invalid
189
191 PMAPI(3), pmFetch(3), pmFetchArchive(3), pmGetInDom(3), pm‐
192 LookupDesc(3), pmLookupInDom(3) and pmNameInDom(3).
193Performance Co-Pilot PCP PMSETMODE(3)