1PMFETCH(3) Library Functions Manual PMFETCH(3)
2
6 pmFetch, pmFetchHighRes, pmHighResFetch - get performance metric values
7
9 #include <pcp/pmapi.h>
10 int pmFetch(int numpmid, pmID *pmidlist, pmResult **result);
12 int pmFetchHighRes(int numpmid, pmID *pmidlist, pmHighResResult **result);
13 cc ... -lpcp
15
17 Given a list of Performance Metric Identifiers (PMID)s, e.g. as con‐
18 structed by pmLookupName(3), via pmidlist and numpmid, fetch the values
19 for these performance metrics.
20 A call to either pmFetch or pmFetchHighRes is executed in the context
22 of a source of metrics, instance profile and collection time, previ‐
23 ously established by calls to the appropriate context and profile func‐
24 tions, namely some of pmNewContext(3), pmDupContext(3), pmUseCon‐
25 text(3), pmAddProfile(3), pmDelProfile(3) and pmSetMode(3).
26 The principal result from pmFetch is returned in the argument result as
28 a tree, using the following component data structures;
29 typedef struct {
31 unsigned int vtype : 8; /* value type (same as pmDesc.type) */
32 unsigned int vlen : 24; /* bytes for vtype/vlen + vbuf */
33 char vbuf[1]; /* one or more values */
34 } pmValueBlock;
35 typedef struct {
37 int inst; /* instance identifier */
38 union {
39 pmValueBlock *pval; /* pointer to value-block */
40 int lval; /* integer value insitu */
41 } value;
42 } pmValue;
43 typedef struct {
45 pmID pmid; /* metric identifier */
46 int numval; /* number of values or error code */
47 int valfmt; /* value style, insitu or ptr */
48 pmValue vlist[1]; /* set of instances/values */
49 } pmValueSet;
50 /* Result returned by pmFetch() */
52 typedef struct {
53 struct timeval timestamp; /* time stamped by collector */
54 int numpmid; /* number of PMIDs */
55 pmValueSet *vset[1]; /* set of value sets */
56 } pmResult;
57 The principal result from pmFetchHighRes is exactly the same in terms
59 of value sets, however a higher resolution timestamp (nanosecond in‐
60 stead of microsecond precision) is available in the pmHighResResult
61 structure.
62 /* Result returned by pmFetchHighRes() */
64 typedef struct {
65 struct timespec timestamp; /* time stamped by collector */
66 int numpmid; /* number of PMIDs */
67 pmValueSet *vset[1]; /* set of value sets */
68 } pmHighResResult;
69 To accommodate metrics with multiple value instances, the numval field
71 indicates how many values are returned for each requested PMID. The
72 field valfmt in the pmValueSet structure indicates if the values for
73 this metric are stored insitu in the lval field, i.e. a 32-bit integer
74 quantity (either int, unsigned int, long or unsigned long) or if the
75 values are held in associated pmValueBlock structures. The pmValue‐
76 Block structure is always used for floating point values (float or dou‐
77 ble) and also accommodates arbitrary sized binary data such as `string-
78 valued' metrics and metrics with aggregated or complex data types. The
79 maximum length of a pmValueBlock buffer is PM_VAL_VLEN_MAX bytes. If
80 the pmValueBlock format is used, the vtype field indicates the data
81 type of the value. This field has the same interpretation as the type
82 field in the pmDesc structure, see pmLookupDesc(3).
83 Note that the insitu value may be a signed or unsigned 32 bit integer,
85 signed or unsigned 32 bit long value (on 32 bit platforms), In the spe‐
86 cial cases described below, it may also be a 32 bit floating point
87 value. If the application needs to know the type of an insitu value,
88 which is almost always the case, it is necessary to fetch the descrip‐
89 tor for the metric and interpret the type field, as described in detail
90 in pmLookupDesc(3). When the pmResult is received from a PCP1.x pmcd,
91 insitu values may also be 32 bit floating point values (of type
92 PM_TYPE_FLOAT). In all cases, it is good practice to use pm‐
93 LookupDesc(3) to fetch the descriptor for the metric and interpret the
94 type field therein. Note also that the PMAPI(3) will automatically
95 translate from the PCP2.0 format to the PCP1.x format when a PCP1.x
96 client requests 32 bit floating point values from a PCP2.0 pmcd, but
97 the reverse translation does not occur (because the PCP2.0 pmcd cannot
98 automatically distinguish between arbitrary 32 bit floating point val‐
99 ues and 32 bit integers).
100 If one value (i.e. associated with a particular instance) for a re‐
102 quested metric is `unavailable' (at the requested time), then there is
103 no associated pmValue structure in the result. If there are no avail‐
104 able values for a metric, then numval will be zero and the associated
105 pmValue[] instance will be empty (valfmt is undefined in these circum‐
106 stances, however pmid will be correctly set to the PMID of the metric
107 with no values).
108 As an extension of this protocol, if the Performance Metrics Collection
110 System (PMCS) is able to provide a reason why no values are available
111 for a particular metric, this is encoded as a standard error code in
112 the corresponding numval. Since the error codes are all negative, val‐
113 ues for a requested metric are `unavailable' if numval is less than, or
114 equal to, zero. A performance metric's value may be `unavailable' for
115 a number of reasons; the following list is illustrative but not exhaus‐
116 tive: of the software for the associated Performance Metric Domain
117 + Collection is not currently activated in the software for the
119 associated Performance Metric Domain
120 + The associated PMID is not known
122 + The current system configuration does not include the associated
124 hardware component and/or the associated software module, e.g. a
125 disk is not installed, or off-line, or Oracle is not installed
126 + The metric is one for which an instance profile is required, and
128 none was provided (there are a small number of metrics in this
129 category, typically ones with very large, and/or very dynamic
130 instance domains, and/or expensive metric instantiation meth‐
131 ods).
132 + If the current context involves fetching metrics from an ar‐
134 chive, values may be unavailable in the region around a <mark>
135 record (see pmlogextract(1)) that indicate a temporal disconti‐
136 nuity in the time-series of metric values.
137 In general, we may not be able to differentiate between the various
139 cases, and if differentiation is not possible, numval will simply be
140 zero.
141 The argument definition and the result specifications have been con‐
143 structed to ensure that for each PMID in the requested pmidlist there
144 is exactly one pmValueSet in the result, and further the PMIDs appear
145 in exactly the same sequence in both pmidlist and result. This makes
146 the number and order of entries in result completely deterministic, and
147 greatly simplifies the application programming logic after the call to
148 pmFetchHighRes or pmFetch.
149 The result structure returned by pmFetch is dynamically allocated using
151 a combination of malloc(3) calls and specialized allocation strategies,
152 and should be released when no longer required by calling pmFreeRe‐
153 sult(3) - under no circumstances should free(3) be called directly to
154 release this space.
155 As common error conditions are encoded in the result data structure,
157 we'd expect only cataclysmic events to cause an error value to be re‐
158 turned. One example would be if the metrics source context was a re‐
159 mote host, and that host or the PMCS on that host became unreachable.
160 Otherwise the value returned by the pmFetch function will be non-nega‐
161 tive.
162 Similarly, the result structure returned by pmFetchHighRes operates un‐
164 der the same principles, and should be released via pmFreeHighResRe‐
165 sult(3).
166 If the current context involves fetching metrics from a Performance
168 Metrics Collector Daemon (PMCD), then the return value may be used to
169 encode out-of-band changes in the state of the PMCD and the associated
170 Performance Metrics Daemon Agents (PMDAs), as a bit-wise ``or'' of the
171 following values:
172 PMCD_RESTART_AGENT An attempt has been made to restart at least one
174 failed PMDA.
175 PMCD_ADD_AGENT At least one PMDA has been started.
177 PMCD_DROP_AGENT PMCD has noticed the termination of at least one
179 PMDA.
180 PMCD_AGENT_CHANGE A convenience macro for any of the three PMDA
182 changes.
183 PMCD_LABEL_CHANGE PMCD has been informed of changes to global (con‐
185 text) labels, or new metrics have appeared which
186 have associated labels.
187 PMCD_NAMES_CHANGE PMCD has been informed that the namespace has been
189 modified, such that new metrics have appeared or
190 existing metrics have been removed.
191 PMCD_HOSTNAME_CHANGE
193 The hostname on the host where PMCD is running has
194 changed. This may be the result of changes from
195 temporary to permanent hostname after a system re‐
196 boot or some subsequent explicit change to the sys‐
197 tem's hostname.
198 The default is to return zero to indicate no change in state, however
200 the pmResult returned by pmFetch (or pmHighResResult returned by pm‐
201 FetchHighRes) has the same interpretation independent of the return
202 value being zero or greater than zero.
203 pmHighResFetch is a previous name for pmFetchHighRes that has been
205 maintained for backwards compatibility.
206
208 pmcd(1), pmAddProfile(3), PMAPI(3), pmDelProfile(3), pmDupContext(3),
209 pmExtractValue(3), pmFetchArchive(3), pmFreeHighResResult(3), pmFreeRe‐
210 sult(3), pmGetInDom(3), pmLookupDesc(3), pmLookupLabels(3), pmLookup‐
211 Name(3), pmNewContext(3), pmSetMode(3), pmUseContext(3) and pmWhichCon‐
212 text(3).
213 Note that pmFetch and pmFetchHighRes are the most primitive methods of
215 fetching metric values from the PMCS. See the pmFetchGroup(3) API for
216 a higher level method that insulates the user from the intricacies of
217 looking up metric names and metadata, setting up instance profiles, pm‐
218 Result traversal, conversions, and scaling.
219
221 As mentioned above, pmFetch and pmFetchHighRes return error codes in‐
222 situ in the argument result. If no result is returned, e.g. due to IPC
223 failure using the current PMAPI context, or end of file on an archive,
224 then these routines will return a negative error code which may be ex‐
225 amined using pmErrStr(3).
226 PM_ERR_EOL
228 When fetching records from an archive, pmFetch returns this er‐
229 ror code to indicate the end of the archive has been passed (or
230 the start of the archive has been passed, if the direction of
231 traversal is backwards in time). If the ``mode'' for the cur‐
232 rent PMAPI context (see pmSetMode(3)) is PM_MODE_INTERP then the
233 time origin is advanced, even when this error code is returned.
234 In this way applications that position the time outside the
235 range defined by the records in the archive, and then commence
236 to pmFetch will eventually see valid results once the time ori‐
237 gin moves inside the temporal span of the archive.
238
240 Many of the performance metrics exported from PCP agents have the se‐
241 mantics of counter meaning they are expected to be monotonically in‐
242 creasing. Under some circumstances, one value of these metrics may be
243 smaller than the previously fetched value. This can happen when a
244 counter of finite precision overflows, or when the PCP agent has been
245 reset or restarted, or when the PCP agent is exporting values from some
246 underlying instrumentation that is subject to some asynchronous discon‐
247 tinuity.
248 The environment variable PCP_COUNTER_WRAP may be set to indicate that
249 all such cases of a decreasing ``counter'' should be treated as a
250 counter overflow, and hence the values are assumed to have wrapped once
251 in the interval between consecutive samples. This ``wrapping'' behav‐
252 ior was the default in earlier PCP versions, but by default has been
253 disabled in PCP version 1.3 and later.
254Performance Co-Pilot PCP PMFETCH(3)