1PMFETCH(3) Library Functions Manual PMFETCH(3)
2
6 pmFetch, pmRequestFetch, pmReceiveFetch - get performance metric values
7
9 #include <pcp/pmapi.h>
10 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 cc ... -lpcp
16
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 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 The principal result from pmFetch is returned in the argument result as
29 a tree, using the following component data structures;
30 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 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 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 /* 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 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 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 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 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 + The metric is not supported in this version of the software for the
107 associated Performance Metric Domain
108 + Collection is not currently activated in the software for the asso‐
110 ciated Performance Metric Domain
111 + The associated PMID is not known
113 + 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 + 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 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 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 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 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 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 PMCD_RESTART_AGENT An attempt has been made to restart at least one
155 failed PMDA.
156 PMCD_ADD_AGENT At least one PMDA has been started.
158 PMCD_DROP_AGENT PMCD has noticed the termination of at least one
160 PMDA.
161 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 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 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
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 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
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 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 PM_ERR_CTXBUSY
213 Context is currently in use by another asynchronous call.
214
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.
230Performance Co-Pilot SGI PMFETCH(3)