1PMFETCH(3)                 Library Functions Manual                 PMFETCH(3)
2
3
4

NAME

6       pmFetch, pmRequestFetch, pmReceiveFetch - get performance metric values
7

C SYNOPSIS

9       #include <pcp/pmapi.h>
10
11       int pmFetch(int numpmid, pmID *pmidlist, pmResult **result)
12       int pmRequestFetch(int cxt, int numpmid, pmID *pmidlist)
13       int pmReceiveFetch(int cxt, pmResult **result)
14
15       cc ... -lpcp
16

DESCRIPTION

18       Given  a list of Performance Metric IDs (PMID)s, e.g. as constructed by
19       pmLookupName(3), via pmidlist and numpmid, fetch the values  for  these
20       performance metrics.
21
22       The  call to pmFetch is executed in the context of a source of metrics,
23       instance profile and collection time, previously established  by  calls
24       to the appropriate context and profile functions, namely some of pmNew‐
25       Context(3), pmDupContext(3), pmUseContext(3),  pmAddProfile(3),  pmDel‐
26       Profile(3) and pmSetMode(3).
27
28       The principal result from pmFetch is returned in the argument result as
29       a tree, using the following component data structures;
30
31            typedef struct {
32                  unsigned int vtype : 8;        /* value type (same as pmDesc.type) */
33                  unsigned int vlen : 24;        /* bytes for vtype/vlen + vbuf */
34                  char         vbuf[1];          /* one or more values */
35            } pmValueBlock;
36
37            typedef struct {
38                  int      inst;                 /* instance identifier */
39                  union {
40                        pmValueBlock *pval;      /* pointer to value-block */
41                        int          lval;       /* integer value insitu */
42                  } value;
43            } pmValue;
44
45            typedef struct {
46                  pmID      pmid;                /* metric identifier */
47                  int       numval;              /* number of values or error code */
48                  int       valfmt;              /* value style, insitu or ptr */
49                  pmValue   vlist[1];            /* set of instances/values */
50            } pmValueSet;
51
52            /* Result returned by pmFetch() */
53            typedef struct {
54                  struct timeval timestamp;      /* time stamped by collector */
55                  int            numpmid;        /* number of PMIDs */
56                  pmValueSet     *vset[1];       /* set of value sets */
57            } pmResult;
58
59       To accommodate metrics with multiple value instances, the numval  field
60       indicates  how  many  values are returned for each requested PMID.  The
61       field valfmt in the pmValueSet structure indicates if  the  values  for
62       this metric are stored insitu in the lval field, i.e. a 32-bit integter
63       quantity (either int, unsigned int, long or unsigned long)  or  if  the
64       values  are  held  in associated pmValueBlock structures.  The pmValue‐
65       Block structure is always used for floating point values (float or dou‐
66       ble) and also accommodates arbitrary sized binary data such as `string-
67       valued' metrics and metrics with aggregated or complex data types.  The
68       maximum  length  of a pmValueBlock buffer is PM_VAL_VLEN_MAX bytes.  If
69       the pmValueBlock format is used, the vtype  field  indicates  the  data
70       type  of the value.  This field has the same interpretation as the type
71       field in the pmDesc structure, see pmLookupDesc(3).
72
73       Note that the insitu value may be a signed or unsigned 32 bit  integer,
74       signed or unsigned 32 bit long value (on 32 bit platforms), In the spe‐
75       cial cases described below, it may also be  a  32  bit  floating  point
76       value.   If  the application needs to know the type of an insitu value,
77       which is almost always the case, it is necessary to fetch the  descrip‐
78       tor for the metric and interpret the type field, as described in detail
79       in pmLookupDesc(3).  When the pmResult is received from a PCP1.x  pmcd,
80       insitu  values  may  also  be  32  bit  floating  point values (of type
81       PM_TYPE_FLOAT).   In  all  cases,  it   is   good   practice   to   use
82       pmLookupDesc(3)  to  fetch  the descriptor for the metric and interpret
83       the type field therein.  Note also that the PMAPI(3) will automatically
84       translate  from  the  PCP2.0  format to the PCP1.x format when a PCP1.x
85       client requests 32 bit floating point values from a  PCP2.0  pmcd,  but
86       the  reverse translation does not occur (because the PCP2.0 pmcd cannot
87       automatically distinguish between arbitrary 32 bit floating point  val‐
88       ues and 32 bit integers).
89
90       If  one  value  (i.e.  associated  with  a  particular  instance) for a
91       requested metric is `unavailable' (at the requested time),  then  there
92       is  no  associated  pmValue  structure  in the result.  If there are no
93       available values for a metric, then numval will be zero and the associ‐
94       ated  pmValue[]  instance  will  be empty (valfmt is undefined in these
95       circumstances, however pmid will be correctly set to the  PMID  of  the
96       metric with no values).
97
98       As an extension of this protocol, if the Performance Metrics Collection
99       System (PMCS) is able to provide a reason why no values  are  available
100       for  a  particular  metric, this is encoded as a standard error code in
101       the corresponding numval.  Since the error codes are all negative, val‐
102       ues for a requested metric are `unavailable' if numval is less than, or
103       equal to, zero.  A performance metric's value may be `unavailable'  for
104       any of the following reasons;
105
106       +  The  metric is not supported in this version of the software for the
107          associated Performance Metric Domain
108
109       +  Collection is not currently activated in the software for the  asso‐
110          ciated Performance Metric Domain
111
112       +  The associated PMID is not known
113
114       +  The  current  system  configuration  does not include the associated
115          hardware component and/or the associated  software  module,  e.g.  a
116          disk is not installed, or off-line, or Oracle is not installed
117
118       +  The  metric  is  one  for which an instance profile is required, and
119          none was provided (there are a small number of metrics in this cate‐
120          gory,  typically  ones with very large, and/or very dynamic instance
121          domains, and/or expensive metric instantiation methods).
122
123       In general, we may not be able to  differentiate  between  the  various
124       cases,  and  if  differentiation is not possible, numval will simply be
125       zero.
126
127       The argument definition and the result specifications  have  been  con‐
128       structed  to  ensure that for each PMID in the requested pmidlist there
129       is exactly one pmValueSet in the result, and further the  PMIDs  appear
130       in  exactly  the same sequence in both pmidlist and result.  This makes
131       the number and order of entries in result completely deterministic, and
132       greatly  simplifies the application programming logic after the call to
133       pmFetch.
134
135       The result structure returned by pmFetch is dynamically allocated using
136       a  combination  of  malloc(3C) calls and specialized allocation strate‐
137       gies, and should  be  released  when  no  longer  required  by  calling
138       pmFreeResult(3)  -  under  no  circumstances  should free(3C) be called
139       directly to release this space.
140
141       As common error conditions are encoded in the  result  data  structure,
142       we'd  expect  only  cataclysmic  events  to  cause an error value to be
143       returned.  One example would be if the metrics  source  context  was  a
144       remote host, and that host or the PMCS on that host became unreachable.
145       Otherwise the value returned by the pmFetch function will be  non-nega‐
146       tive.
147
148       If  the  current  context  involves fetching metrics from a Performance
149       Metrics Collector Daemon (PMCD), then the return value may be  used  to
150       encode  out-of-band changes in the state of the PMCD and the associated
151       Performance Metrics Daemon Agents (PMDAs), as a bit-wise ``or'' of  the
152       following values:
153
154       PMCD_RESTART_AGENT  An  attempt  has  been made to restart at least one
155                           failed PMDA.
156
157       PMCD_ADD_AGENT      At least one PMDA has been started.
158
159       PMCD_DROP_AGENT     PMCD has noticed the termination of  at  least  one
160                           PMDA.
161
162       The  default  is to return zero to indicate no change in state, however
163       the pmResult returned by pmFetch has the same  interpretation  indepen‐
164       dent of the return value being zero or greater than zero.
165
166       pmRequestFetch  and  pmReceiveFetch are used by applications which must
167       communicate with the PMCD asynchronously.  These functions take explict
168       context  handle ctx which must refer to a host context (i.e. created by
169       passing PM_CONTEXT_HOST to pmNewContext). pmRequestFetch sends a  fetch
170       request  to  PMCD  and  returns without waiting for the response, pmRe‐
171       ceiveFetch reads the reply from PMCD. It is the responsibility  of  the
172       application  to  make sure the data are ready before calling pmReceive‐
173       Fetch to avoid blocking while reading the reply.
174
175       pmReceiveFetch can return a positive value to indicate a change in  the
176       state of PMCD. In this case the result is unchanged and the application
177       is expected to call pmReceiveFetch again.
178

SEE ALSO

180       pmcd(1), pmAddProfile(3), PMAPI(3),  pmDelProfile(3),  pmDupContext(3),
181       pmExtractValue(3),  pmFetchArchive(3),  pmFreeResult(3), pmGetInDom(3),
182       pmLookupDesc(3),   pmLookupName(3),   pmNewContext(3),    pmSetMode(3),
183       pmUseContext(3) and pmWhichContext(3).
184
185       Note  that pmFetch is the most primitive method of fetching metric val‐
186       ues from the PMCS.  More user  friendly  interfaces  to  the  PMCS  are
187       available  or  currently  under  development - these higher level fetch
188       methods insulate the user from the  intricacies  of  context  creation,
189       setting up instance profiles, pmResult traversal, and splitting fetches
190       into batches to minimize PDU traffic or according to other optimization
191       criteria.
192

DIAGNOSTICS

194       As  mentioned above, pmFetch returns error codes insitu in the argument
195       result.  If no result is returned, e.g. due to IPC  failure  using  the
196       current  PMAPI  context, or end of file on an archive log, then pmFetch
197       will  return  a  negative  error  code  which  may  be  examined  using
198       pmErrStr(3).
199
200       PM_ERR_EOL
201              When  fetching records from an archive log, pmFetch returns this
202              error code to indicate the end of the log has  been  passed  (or
203              the  start  of the log has been passed, if the direction of tra‐
204              versal is backwards in time).  If the ``mode'' for  the  current
205              PMAPI context (see pmSetMode(3)) is PM_MODE_INTERP then the time
206              origin is advanced, even when this error code is  returned.   In
207              this  way  applications that position the time outside the range
208              defined by the records in the  archive,  and  then  commence  to
209              pmFetch  will  eventually see valid results once the time origin
210              moves inside the temporal span of the archive.
211
212       PM_ERR_CTXBUSY
213              Context is currently in use by another asynchronous call.
214

ENVIRONMENT

216       Many of the performance metrics  exported  from  PCP  agents  have  the
217       semantics  of  counter  meaning  they  are expected to be monotonically
218       increasing.  Under some circumstances, one value of these  metrics  may
219       be  smaller  than the previously fetched value.  This can happen when a
220       counter of finite precision overflows, or when the PCP agent  has  been
221       reset or restarted, or when the PCP agent is exporting values from some
222       underlying instrumentation that is subject to some asynchronous discon‐
223       tinuity.
224       The  environment  variable PCP_COUNTER_WRAP may be set to indicate that
225       all such cases of a decreasing  ``counter''  should  be  treated  as  a
226       counter overflow, and hence the values are assumed to have wrapped once
227       in the interval between consecutive samples.  This ``wrapping''  behav‐
228       ior  was  the  default in earlier PCP versions, but by default has been
229       disabled in PCP version 1.3 and later.
230
231
232
233Performance Co-Pilot                  SGI                           PMFETCH(3)
Impressum