pmsetmode(3)
NAME
pmSetMode - set collection time parameters for the current PMAPI context
C SYNOPSIS
#include <pcp/pmapi.h> int pmSetMode(int mode, const struct timeval *when, int delta); cc ... -lpcp
DESCRIPTION
pmSetMode is used to define the collection time and/or mode for accessing performance metrics and meta-data in the current Performance Metrics Application Programming Interface (PMAPI) context. This mode affects the semantics of subsequent calls to the following PMAPI routines: pmFetch(3), pmFetchArchive(3), pmLookupDesc(3), pmGetInDom(3), pmLookupInDom(3) and pmNameInDom(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 are ignored. PM_MODE_LIVE is the default mode when a new PMAPI context of type PM_CONTEXT_HOST is created. If the mode is not PM_MODE_LIVE, then the when parameter defines a time origin, and all requests for meta-data (metric descriptions and instance identifiers from the instance domains) will be processed to reflect the state of the meta-data as of the time origin, i.e. we use the last state of this information at, or before, the time origin. If the mode is PM_MODE_INTERP then, in the case of pmFetch(3), the underlying code will use an interpolation scheme to compute the values of the metrics from the values recorded for times in the proximity of the time origin. A mode of PM_MODE_INTERP may only be used with an archive context. If the mode is PM_MODE_FORW then, in the case of pmFetch(3), the collection of recorded metric values will be scanned in a forwards direction in time, until values for at least one of the requested metrics is located after the time origin, and then all requested metrics stored in the set of archives at that time will be returned with the corresponding timestamp. A mode of PM_MODE_FORW may only be used with an archive context. If the mode is PM_MODE_BACK then, the situation is the same as for PM_MODE_FORW, except a pmFetch(3) will be serviced by scanning the collection of recorded metrics in a backwards direction in time for metrics before the time origin. A mode of PM_MODE_BACK may only be used with an archive context. If the mode is PM_MODE_FORW or PM_MODE_BACK, and no qualifying metrics can be found in the requested direction of searching before the end or start of the set of archive logs is found, then pmFetch(3) returns the special error indicator, PM_ERR_EOL. For modes other than PM_MODE_LIVE, after each successful pmFetch(3), the time origin is reset to the timestamp returned via the pmResult structure from pmFetch(3). The pmSetMode parameter delta defines an additional number of time units that should be used to adjust the time origin (forwards or backwards), after the new time origin from the pmResult has been determined. This automatic adjustment of the time origin only occurs when the mode is PM_MODE_INTERP, and the adjustment is applied, even if the pmFetch(3) fails because the time origin is outside the range defined by the records in a set of archive logs, i.e. returns PM_ERR_EOL. By default delta is interpreted as milliseconds (but see the LARGE DELTA VALUES section below). Using these mode options, an application can implement replay, playback, fast forward, reverse, etc. for performance metric values held in the set of archive logs by alternating calls to pmSetMode and pmFetch(3). As a special case, if when is NULL then the mode and delta arguments are used as described above, but the current time in the archive is not altered.
EXAMPLES
The following code fragment may be used to dump just those values
recorded in an archive in correct temporal sequence, for a selected set
of performance metrics; this uses the default collection time
mechanisms.
pmNewContext(PM_CONTEXT_ARCHIVE, "myarchive");
while (pmFetch(npmid, pmidlist, &result) != PM_ERR_EOL) {
/*
* process real metric values as of result->timestamp
*/
. . .
pmFreeResult(result);
}
Alternatively, to replay interpolated metrics from the log in reverse
chronological order, at 10 second intervals (of recorded time), the
following code fragment could be used.
struct timeval mytime;
mytime.tv_sec = 0x7fffffff; /* or use pmGetArchiveEnd(&mtime) */
pmSetMode(PM_MODE_BACK, &mytime, 0);
pmFetchArchive(&result);
mytime = result->timestamp;
pmFreeResult(result);
pmSetMode(PM_MODE_INTERP | PM_XTB_SET(PM_TIME_SEC), &mytime, -10);
while (pmFetch(numpmid, pmidlist, &result) != PM_ERR_EOL) {
/*
* process interpolated metric values as of
* result->timestamp
*/
. . .
pmFreeResult(result);
}
LARGE DELTA VALUES
Because delta is an int and treated as milliseconds by default there is
a limit on the maximum absolute value of delta that can be specified
with this default interpretation, namely about 24 days if a signed int
has 31 bits of precision. To accommodate longer values of delta the
high-order bits of the mode parameter is also used to optionally set
the units of time for the delta parameter. To specify the units of time
use the PM_XTB_SET macro with one of the values PM_TIME_NSEC,
PM_TIME_MSEC, PM_TIME_SEC, etc. to set the mode as follows:
PM_MODE_INTERP | PM_XTB_SET(PM_TIME_XXXX)
The following code shows how this could be done if the desired delta is
initially encoded in interval (a struct timeval).
struct timeval interval;
int mode;
mode = ...
if (abs(interval.tv_sec / (3600*24)) <= 24) {
/* default encoding of milliseconds is fine */
mode = PM_MODE_INTERP;
delta = interval.tv_sec * 1000 + (interval.tv_usec + 500)/ 1000;
}
else {
/* encode delta in units of seconds */
mode = PM_MODE_INTERP | PM_XTB_SET(PM_TIME_SEC);
delta = interval.tv_sec + (interval.tv_usec + 500000)/ 1000000;
}
For millisecond encoding of delta, using PM_XTB_SET(PM_TIME_MSEC) is
functionally equivalent to not using PM_XTB_SET at all.
SEE ALSO
PMAPI(3), pmFetch(3), pmFetchArchive(3), pmGetInDom(3), pmLookupDesc(3), pmLookupInDom(3) and pmNameInDom(3).
DIAGNOSTICS
PM_ERR_MODE
The mode parameter is invalid
Opportunity
Personal Opportunity - Free software gives you access to billions of dollars of software at no cost. Use this software for your business, personal use or to develop a profitable skill. Access to source code provides access to a level of capabilities/information that companies protect though copyrights. Open source is a core component of the Internet and it is available to you. Leverage the billions of dollars in resources and capabilities to build a career, establish a business or change the world. The potential is endless for those who understand the opportunity.
Business Opportunity - Goldman Sachs, IBM and countless large corporations are leveraging open source to reduce costs, develop products and increase their bottom lines. Learn what these companies know about open source and how open source can give you the advantage.
Free Software
Free Software provides computer programs and capabilities at no cost but more importantly, it provides the freedom to run, edit, contribute to, and share the software. The importance of free software is a matter of access, not price. Software at no cost is a benefit but ownership rights to the software and source code is far more significant.
Free Office Software - The Libre Office suite provides top desktop productivity tools for free. This includes, a word processor, spreadsheet, presentation engine, drawing and flowcharting, database and math applications. Libre Office is available for Linux or Windows.
Free Books
The Free Books Library is a collection of thousands of the most popular public domain books in an online readable format. The collection includes great classical literature and more recent works where the U.S. copyright has expired. These books are yours to read and use without restrictions.
Source Code - Want to change a program or know how it works? Open Source provides the source code for its programs so that anyone can use, modify or learn how to write those programs themselves. Visit the GNU source code repositories to download the source.
Education
Study at Harvard, Stanford or MIT - Open edX provides free online courses from Harvard, MIT, Columbia, UC Berkeley and other top Universities. Hundreds of courses for almost all major subjects and course levels. Open edx also offers some paid courses and selected certifications.
Linux Manual Pages - A man or manual page is a form of software documentation found on Linux/Unix operating systems. Topics covered include computer programs (including library and system calls), formal standards and conventions, and even abstract concepts.
