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 log or archive at that time will be returned with the corresponding
47 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 archive log is found, then pmFetch(3) returns the special
59 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 an archive log, i.e. returns PM_ERR_EOL. The high-
72 order bits of the mode parameter is also used to optionally set the
73 units of time for the delta field. To specify the units of time use
74 PM_XTB_SET macro with one of the values PM_TIME_NSEC, PM_TIME_MSEC,
75 PM_TIME_SEC, etc. as follows:
76 PM_MODE_INTERP | PM_XTB_SET(PM_TIME_XXXX)
78 If no units are specified the default is to interpret delta as mil‐
80 liseconds.
81 Using these mode options, an application can implement replay, play‐
83 back, fast forward, reverse, etc. for performance metric values held in
84 the archive log by alternating calls to pmSetMode and pmFetch(3).
85 As a special case, if when is NULL then the mode and delta arguments
87 are used as described above, but the current time in the archive is not
88 altered.
89 For example, the following code fragment may be used to dump just those
91 values recorded in an archive in correct temporal sequence, for a
92 selected set of performance metrics; this uses the default collection
93 time mechanisms.
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 = 0x7fffffff; /* 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
127 PMAPI(3), pmFetch(3), pmFetchArchive(3), pmGetInDom(3),
128 pmLookupDesc(3), pmLookupInDom(3) and pmNameInDom(3).
129
131 PM_ERR_MODE
132 The mode parameter is invalid
133Performance Co-Pilot PCP PMSETMODE(3)