pmfetch(3) — Linux manual page

NAME | C SYNOPSIS | DESCRIPTION | SEE ALSO | DIAGNOSTICS | ENVIRONMENT | COLOPHON

PMFETCH(3)              Library Functions Manual              PMFETCH(3)

NAME         top

       pmFetch - get performance metric values

C SYNOPSIS         top

       #include <pcp/pmapi.h>

       int pmFetch(int numpmid, pmID *pmidlist, pmResult **result);

       cc ... -lpcp

DESCRIPTION         top

       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.

       The call to pmFetch is executed in the context of a source of
       metrics, 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
       result 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 timeval 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
       pmValueBlock structures.  The pmValueBlock structure is always
       used for floating point values (float or double) and also
       accommodates arbitrary sized binary data such as `string-valued'
       metrics and metrics with aggregated or complex data types.  The
       maximum length of a pmValueBlock buffer is PM_VAL_VLEN_MAX bytes.
       If the pmValueBlock 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
       integer, 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 necessary to fetch the descriptor for the metric and interpret
       the type field, as described in detail in pmLookupDesc(3).  When
       the pmResult 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 translation 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
       undefined 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
       Collection System (PMCS) is able to provide a reason why no
       values are available for a particular metric, this is encoded as
       a standard error code in the corresponding numval.  Since the
       error codes are all negative, values for a requested metric are
       `unavailable' if numval is less than, or equal to, zero.  A
       performance 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
              associated hardware component and/or the associated
              software module, e.g. a disk is not installed, or off-
              line, or Oracle is not installed

       +      The metric is one for which an instance profile is
              required, 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 metric instantiation methods).

       +      If the current context involves fetching metrics from an
              archive log, values may be unavailable in the region
              around a <mark> record (see pmlogextract(1)) that indicate
              a temporal discontinuity in the time-series of metric
              values.

       In general, we may not be able to differentiate between the
       various 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 result.  This makes the number and order of entries
       in result completely deterministic, and greatly simplifies the
       application programming 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
       structure, we'd expect only cataclysmic events to cause an error
       value to be returned.  One example would be if the metrics source
       context was a remote host, and that host or the PMCS on that host
       became unreachable.  Otherwise the value returned by the pmFetch
       function will be non-negative.

       If the current context involves fetching metrics from a
       Performance 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
                           appeared or existing metrics have been
                           removed.

       The default is to return zero to indicate no change in state,
       however the pmResult returned by pmFetch has the same
       interpretation independent of the return value being zero or
       greater than zero.

SEE ALSO         top

       pmcd(1), pmAddProfile(3), PMAPI(3), pmDelProfile(3),
       pmDupContext(3), pmExtractValue(3), pmFetchArchive(3),
       pmFreeResult(3), pmGetInDom(3), pmLookupDesc(3),
       pmLookupLabels(3), pmLookupName(3), pmNewContext(3),
       pmSetMode(3), pmUseContext(3) and pmWhichContext(3).

       Note that pmFetch is the most primitive method of fetching metric
       values from the PMCS.  See the pmFetchGroup(3) API for a higher
       level method that insulates the user from the intricacies of
       looking up metric names and metadata, setting up instance
       profiles, pmResult traversal, conversions, and scaling.

DIAGNOSTICS         top

       As mentioned above, pmFetch returns error codes insitu in the
       argument result.  If no result is returned, e.g. due to IPC
       failure using the current PMAPI context, or end of file on an
       archive log, then pmFetch will return a negative error code which
       may be examined using pmErrStr(3).

       PM_ERR_EOL
              When fetching records from an archive log, pmFetch returns
              this error code to indicate the end of the log has been
              passed (or the start of the log 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 inside the temporal span of the archive.

ENVIRONMENT         top

       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 exporting values from some underlying instrumentation
       that is subject 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.

COLOPHON         top

       This page is part of the PCP (Performance Co-Pilot) project.
       Information about the project can be found at 
       ⟨http://www.pcp.io/⟩.  If you have a bug report for this manual
       page, send it to pcp@groups.io.  This page was obtained from the
       project's upstream Git repository
       ⟨https://github.com/performancecopilot/pcp.git⟩ on 2020-12-18.
       (At that time, the date of the most recent commit that was found
       in the repository was 2020-12-18.)  If you discover any rendering
       problems in this HTML version of the page, or you believe there
       is a better or more up-to-date source for the page, or you have
       corrections or improvements to the information in this COLOPHON
       (which is not part of the original manual page), send a mail to
       man-pages@man7.org

Performance Co-Pilot               PCP                        PMFETCH(3)

Pages that refer to this page: pmdaopenmetrics(1)pmgenmap(1)pmstore(1)pcpintro(3)pmaddprofile(3)pmapi(3)__pmcontrollog(3)pmconvscale(3)pmdafetch(3)pmdelprofile(3)pmextractvalue(3)pmfetcharchive(3)pmfetchgroup(3)pmfreeresult(3)pmgetarchiveend(3)pmgetcontexthostname(3)pmgetderivedcontrol(3)pmlookuplabels(3)pmnewcontext(3)pmnewcontextzone(3)pmprintvalue(3)pmregisterderived(3)pmsetmode(3)pmsortinstances(3)pmstore(3)pmwebapi(3)QmcIndom(3)