# pmfetch

## NAME



           **pmFetch** - get performance metric values
    


## C SYNOPSIS



           **#include <pcp/pmapi.h>**
    
           **int pmFetch(int** _numpmid_**, pmID ***_pmidlist_**, pmResult ****_result_**);**
    
           **cc ... -lpcp**
    


## DESCRIPTION



           Given  a  list  of Performance Metric Identifiers (PMID)s, e.g. as
           constructed by pmLookupName(3), via _pmidlist_  and  _numpmid_ ,  fetch
           the values for these performance metrics.
    
           A  call  to **pmFetch** is executed in the context of a source of met‐
           rics, instance profile and collection time, previously established
           by calls to the appropriate context and profile functions,  namely
           some   of   pmNewContext(3),   pmDupContext(3),   pmUseContext(3),
           pmAddProfile(3), pmDelProfile(3) and pmSetMode(3).
    
           The principal result from **pmFetch** is returned in the argument  _re‐_
           _sult_ as a tree, using the following component data structures;
    
                typedef struct {
                      unsigned int vtype : 8;        /* value type (same as pmDesc.type) */
                      unsigned int vlen : 24;        /* bytes for vtype/vlen + vbuf */
                      char         vbuf[1];          /* one or more values */
                } pmValueBlock;
    
                typedef struct {
                      int      inst;                 /* instance identifier */
                      union {
                            pmValueBlock *pval;      /* pointer to value-block */
                            int          lval;       /* integer value insitu */
                      } value;
                } pmValue;
    
                typedef struct {
                      pmID      pmid;                /* metric identifier */
                      int       numval;              /* number of values or error code */
                      int       valfmt;              /* value style, insitu or ptr */
                      pmValue   vlist[1];            /* set of instances/values */
                } pmValueSet;
    
                /* Result returned by pmFetch() */
                typedef struct {
                      struct timespec timestamp;     /* time stamped by collector */
                      int            numpmid;        /* number of PMIDs */
                      pmValueSet     *vset[1];       /* set of value sets */
                } pmResult;
    
           To  accommodate  metrics with multiple value instances, the _numval_
           field indicates how many values are returned  for  each  requested
           PMID.   The  field _valfmt_ in the _pmValueSet_ structure indicates if
           the values for this metric are stored _insitu_ in  the  _lval_  field,
           i.e.  a 32-bit integer quantity (either int, unsigned int, long or
           unsigned long) or if the values are held  in  associated  _pmValue‐_
           _Block_  structures.   The _pmValueBlock_ structure is always used for
           floating point values (float or double) and also accommodates  ar‐
           bitrary sized binary data such as `string-valued' metrics and met‐
           rics with aggregated or complex data types.  The maximum length of
           a  _pmValueBlock_  buffer is **PM_VAL_VLEN_MAX** bytes.  If the _pmValue‐_
           _Block_ format is used, the _vtype_ field indicates the data  type  of
           the  value.   This  field  has the same interpretation as the _type_
           field in the **pmDesc** structure, see pmLookupDesc(3).
    
           Note that the insitu value may be a signed or unsigned 32 bit  in‐
           teger, signed or unsigned 32 bit long value (on 32 bit platforms),
           In  the  special  cases  described  below, it may also be a 32 bit
           floating point value.  If the application needs to know  the  type
           of  an insitu value, which is almost always the case, it is neces‐
           sary to fetch the descriptor for the metric and interpret the **type**
           field, as described in detail in pmLookupDesc(3).  When the  _pmRe‐_
           _sult_  is received from a PCP1.x **pmcd** , insitu values may also be 32
           bit floating point values (of type **PM_TYPE_FLOAT**).  In all  cases,
           it is good practice to use pmLookupDesc(3) to fetch the descriptor
           for  the  metric  and interpret the **type** field therein.  Note also
           that the PMAPI(3) will automatically  translate  from  the  PCP2.0
           format  to  the PCP1.x format when a PCP1.x client requests 32 bit
           floating point values from a PCP2.0 **pmcd** , but the reverse transla‐
           tion does not occur (because the PCP2.0 **pmcd** cannot  automatically
           distinguish  between arbitrary 32 bit floating point values and 32
           bit integers).
    
           If one value (i.e. associated with a particular  instance)  for  a
           requested  metric  is  `unavailable' (at the requested time), then
           there is no associated _pmValue_ structure in the _result_.  If  there
           are no available values for a metric, then _numval_ will be zero and
           the  associated  _pmValue[]_ instance will be empty (_valfmt_ is unde‐
           fined in these circumstances, however _pmid_ will be  correctly  set
           to the PMID of the metric with no values).
    
           As  an extension of this protocol, if the Performance Metrics Col‐
           lection System (PMCS) is able to provide a reason  why  no  values
           are  available for a particular metric, this is encoded as a stan‐
           dard error code in the  corresponding  _numval_.   Since  the  error
           codes  are  all  negative,  values for a requested metric are `un‐
           available' if _numval_ is less than, or equal to, zero.   A  perfor‐
           mance metric's value may be `unavailable' for a number of reasons;
           the  following  list  is  illustrative  but not exhaustive: of the
           software for the associated Performance Metric Domain
    
           +      Collection is not currently activated in the software for
                  the associated Performance Metric Domain
    
           +      The associated PMID is not known
    
           +      The current system configuration does not include the asso‐
                  ciated hardware component and/or the associated software
                  module, e.g. a disk is not installed, or off-line, or Ora‐
                  cle is not installed
    
           +      The metric is one for which an instance profile is re‐
                  quired, and none was provided (there are a small number of
                  metrics in this category, typically ones with very large,
                  and/or very dynamic instance domains, and/or expensive met‐
                  ric instantiation methods).
    
           +      If the current context involves fetching metrics from an
                  archive, values may be unavailable in the region around a
                  _< mark>_ record (see pmlogextract(1)) that indicate a tempo‐
                  ral discontinuity in the time-series of metric values.
    
           In general, we may not be able to differentiate between the vari‐
           ous cases, and if differentiation is not possible, _numval_ will
           simply be zero.
    
           The argument definition and the result specifications have been
           constructed to ensure that for each PMID in the requested _pmidlist_
           there is exactly one _pmValueSet_ in the _result_ , and further the
           PMIDs appear in exactly the same sequence in both _pmidlist_ and _re‐_
           _sult_.  This makes the number and order of entries in _result_ com‐
           pletely deterministic, and greatly simplifies the application pro‐
           gramming logic after the call to **pmFetch**.
    
           The _result_ structure returned by **pmFetch** is dynamically allocated
           using a combination of malloc(3) calls and specialized allocation
           strategies, and should be released when no longer required by
           calling pmFreeResult(3) - under no circumstances should free(3) be
           called directly to release this space.
    
           As common error conditions are encoded in the _result_ data struc‐
           ture, we'd expect only cataclysmic events to cause an error value
           to be returned.  One example would be if the metrics source con‐
           text was a remote host, and that host or the PMCS on that host be‐
           came unreachable.  Otherwise the value returned by the **pmFetch**
           function will be non-negative.
    
           If the current context involves fetching metrics from a Perfor‐
           mance Metrics Collector Daemon (PMCD), then the return value may
           be used to encode out-of-band changes in the state of the PMCD and
           the associated Performance Metrics Daemon Agents (PMDAs), as a
           bit-wise ``or'' of the following values:
    
           **PMCD_RESTART_AGENT** An attempt has been made to restart at least
                               one failed PMDA.
    
           **PMCD_ADD_AGENT** At least one PMDA has been started.
    
           **PMCD_DROP_AGENT** PMCD has noticed the termination of at least
                               one PMDA.
    
           **PMCD_AGENT_CHANGE** A convenience macro for any of the three PMDA
                               changes.
    
           **PMCD_LABEL_CHANGE** PMCD has been informed of changes to global
                               (context) labels, or new metrics have appeared
                               which have associated labels.
    
           **PMCD_NAMES_CHANGE** PMCD has been informed that the namespace has
                               been modified, such that new metrics have ap‐
                               peared or existing metrics have been removed.
    
           **PMCD_HOSTNAME_CHANGE**
                               The hostname on the host where PMCD is running
                               has changed.  This may be the result of
                               changes from temporary to permanent hostname
                               after a system reboot or some subsequent ex‐
                               plicit change to the system's hostname.
    
           The default is to return zero to indicate no change in state, how‐
           ever the _pmResult_ returned by **pmFetch** has the same interpretation
           independent of the return value being zero or greater than zero.
    


## COMPATIBILITY



           Prior to PCP 7.0 the _timestamp_ field in the pmResult struct was a
           struct timeval.  To support PMAPI transition, the old interface
           and semantics can be used if applications are recompiled with
           **-DPMAPI_VERSION=2**.
    
           For a time in PCP 6.x there was a routine with the same semantics
           as the current **pmFetch** called **pmFetchHighRes** , and a struct with
           the same definition as the current pmResult struct called pmRe‐
           sultHighRes, although both are now deprecated and compile-time
           support for **pmFetchHighRes**(and the historically misnamed alias
           **pmHighResFetch**) and pmResultHighRes will be removed in a future
           release.
    


## DIAGNOSTICS



           As mentioned above, **pmFetch** return error codes _insitu_ in the argu‐
           ment _result_.  If no result is returned, e.g. due to IPC failure
           using the current PMAPI context, or end of file on an archive,
           then these routines will return a negative error code which may be
           examined using pmErrStr(3).
    
           **PM_ERR_EOL**
                  When fetching records from an archive, **pmFetch** returns this
                  error code to indicate the end of the archive has been
                  passed (or the start of the archive has been passed, if the
                  direction of traversal is backwards in time).  If the
                  ``mode'' for the current PMAPI context (see pmSetMode(3))
                  is **PM_MODE_INTERP** then the time origin is advanced, even
                  when this error code is returned.  In this way applications
                  that position the time outside the range defined by the
                  records in the archive, and then commence to **pmFetch** will
                  eventually see valid results once the time origin moves in‐
                  side the temporal span of the archive.
    
           **-EAGAIN**
                  If the current context involves fetching metrics from **pmcd** ,
                  then a return value of **-EAGAIN** indicates the caller has
                  created too many contexts.
    


## ENVIRONMENT



           Many of the performance metrics exported from PCP agents have the
           semantics of _counter_ meaning they are expected to be monotonically
           increasing.  Under some circumstances, one value of these metrics
           may be smaller than the previously fetched value.  This can happen
           when a counter of finite precision overflows, or when the PCP
           agent has been reset or restarted, or when the PCP agent is ex‐
           porting values from some underlying instrumentation that is sub‐
           ject to some asynchronous discontinuity.
           The environment variable **PCP_COUNTER_WRAP** may be set to indicate
           that all such cases of a decreasing ``counter'' should be treated
           as a counter overflow, and hence the values are assumed to have
           wrapped once in the interval between consecutive samples.  This
           ``wrapping'' behavior was the default in earlier PCP versions, but
           by default has been disabled in PCP version 1.3 and later.
    


* * *