pmfetcharchive(3) [centos man page]

PMFETCHARCHIVE(3)					     Library Functions Manual						 PMFETCHARCHIVE(3)

NAME

       pmFetchArchive - get performance metrics directly from an archive log

C SYNOPSIS

       #include <pcp/pmapi.h>

       int pmFetchArchive(pmResult **result);

       cc ... -lpcp

DESCRIPTION

       pmFetchArchive  is  a  variant  of  pmFetch(3) that may only be used when the current Performance Metrics Application Programming Interface
       (PMAPI) context is associated with an archive log.

       The result is instantiated with all of the metrics (and instances) from the next archive record, consequently there is no notion of a  list
       of desired metrics, and the instance profile of the PMAPI context is ignored.

       It  is  expected that pmFetchArchive would be used to create utilities that scan archive logs, while the more common access to the archives
       would be via the pmFetch(3) interface.

       To skip records within the archive log, use pmSetMode(3) to change the  collection  time  within  the  current  PMAPI  context,	then  call
       pmFetchArchive.

       Note  that  the	result returned by pmFetchArchive is dynamically allocated, and must be released using pmFreeResult(3), not free(3C).  See
       pmFetch(3) and pmFreeResult(3) for further details.

       pmFetchArchive returns zero on success.

SEE ALSO

       PMAPI(3), pmFetch(3), pmFreeResult(3), pmNewContext(3), pmSetMode(3) and pmTrimNameSpace(3).

DIAGNOSTICS

       PM_ERR_NOTARCHIVE
	      the current PMAPI context is not associated with an archive log

Performance Co-Pilot							PCP							 PMFETCHARCHIVE(3)

PMSETMODE(3)						     Library Functions Manual						      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 Met-
       rics Application Programming Interface (PMAPI) context.	This mode affects the semantics of subsequent calls to the  following  PMAPI  rou-
       tines: 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_CON-
       TEXT_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 direc-
       tion 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 log or archive 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  col-
       lection	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 archive log 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  back-
       wards), 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 an archive log, i.e. returns PM_ERR_EOL.	The high-order bits of the mode parameter is also used to optionally set the units
       of time for the delta field. To specify the units of time  use  PM_XTB_SET  macro  with	one  of  the  values  PM_TIME_NSEC,  PM_TIME_MSEC,
       PM_TIME_SEC, etc.  as follows:

	    PM_MODE_INTERP | PM_XTB_SET(PM_TIME_XXXX)

       If no units are specified the default is to interpret delta as milliseconds.

       Using  these mode options, an application can implement replay, playback, fast forward, reverse, etc. for performance metric values held in
       the archive log 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.

       For  example,  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;
	    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);
	    }

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

Performance Co-Pilot							PCP							      PMSETMODE(3)