1PMWEBAPI(3) Library Functions Manual PMWEBAPI(3)
2
3
4
6 PMWEBAPI - introduction to the Performance Metrics Web Application Pro‐
7 gramming Interface
8
9
10
12 The PMWEBAPI interface is a binding of a subset of the PMAPI to the
13 web. It uses HTTP as transport, REST as organizational style for
14 request/parameter encoding (the GET and POST methods are interchange‐
15 able), and JSON as response encoding. A context identifier is used as
16 a persistent way to refer to PMAPI contexts across related web
17 requests. These context identifiers expire after a configurable period
18 of disuse.
19
20 Errors generally result in HTTP-level error responses. An Access-
21 Control-Allow-Origin: * header is added to all JSON responses.
22
23
25 To create a new web context identifier, a web client invokes:
26
27 /pmapi/context?hostname=STRING
28
29 /pmapi/context?hostspec=STRING
30 Creates a PM_CONTEXT_HOST PMAPI context with the given host name
31 and/or extended specification. If the host specification con‐
32 tains a userid/password combination, then the corresponding
33 PMAPI context operations will require HTTP Basic authentication
34 credentials with matching userid/password.
35
36 In addition, the web client may add the parameter &polltimeout=MMMM for
37 a maximum interval (in seconds) between expected accesses to the given
38 context. This value is limited by pmwebd configuration, and is a cour‐
39 tesy to allow pmwebd to free up memory earlier in case of sudden web
40 application shutdown.
41
42 If successful, the response from these requests is a JSON document of
43 the form:
44
45 { "context" : NNNNN }
46
47 The number (a 32-bit unsigned decimal) is then used in all later opera‐
48 tions.
49
50
52 In addition, permanent contexts may be created by pmwebd at initializa‐
53 tion using its -h, -a, -L command line options, so that a set of fixed
54 NNNNN numbers may be made available to web clients.
55
56
58 The general form of the requests is as follows: /pmapi/NNNNN/OPERATION
59 where
60
61 /pmapi is the fixed prefix for all PMWEBAPI operations,
62
63 NNNNN is a PMWEBAPI context number returned from a context-creation
64 call, or assigned permanently at pmwebd startup, and
65
66 OPERATION?PARAM1=VALUE2&PARAM2=VALUE2
67 identifies the operation and its URL-encoded parameters. Some
68 parameters may be optional.
69
70
71 METRIC METADATA: pmLookupName, pmLookupDesc, pmLookupText, pmTraversePMNS_r
72 The general form of the requests is as follows:
73
74 /pmapi/NNNNN/_metric
75 Traverse the entire Performance Metrics Name Space (PMNS).
76
77 /pmapi/NNNNN/_metric?prefix=NAME
78 Traverse the subtree of PMNS with the prefix NAME.
79
80 The response is a JSON document that provides the metric metadata as an
81 array. For example:
82
83 { "metrics": [
84 { "name":"foo.bar", "pmID":PPPP, "indom":DDDD,
85 "type":"32", "sem":"instant", "units":"MHz",
86 "text-oneline":"foo bar", "text-help":"blah blah blah" },
87 { "name":"foo.bar2", ... }
88 ...
89 ] }
90
91 Most of the fields are self-explanatory.
92
93 name A name for the metric as defined in the PMNS. If the PMNS con‐
94 tains multiple names associated with the metric's Performance
95 Metric Identifier (PMID), one of these will be returned via
96 name, but there is no way to determine which of the duplicate
97 names this will be.
98
99 PPPP the PMID
100
101 DDDD the instance domain
102
103 type from pmTypeStr
104
105 units from pmUnitsStr
106
107 sem an abbreviation of the metric semantic:
108
109 PM_SEM_COUNTER "counter"
110 PM_SEM_INSTANT "instant"
111 PM_SEM_DISCRETE "discrete"
112
113
114 METRIC VALUE: pmFetch
115 The general form of the requests is as follows:
116
117 /pmapi/NNNNN/_fetch?names=NAME1,NAME2
118 Fetch current values for given named metrics.
119
120 /pmapi/NNNNN/_fetch?pmids=PPPP1,PPPP2
121 Fetch current values for given PMIDs.
122
123 If any of the names/pmids are valid, the response is a JSON document
124 that provides the values for all requested metrics, for all their in‐
125 stances.
126
127 { "timestamp": { "s":SEC, "us":USEC },
128 "values": [
129 { "pmid":PPPP1, "name":"NAME1",
130 "instances:" [
131 { "instance":IIII1, "value":VALUE1 }
132 { "instance":IIII2, "value":VALUE2 }
133 ...
134 ] },
135 { "pmid":PPPP2, "name":"NAME2", ... }
136 ...
137 ] }
138
139 Most of the fields are self-explanatory. Numeric metric types are rep‐
140 resented as JSON integer or floating-point values. Strings are passed
141 verbatim, except that non-ASCII values are replaced with a Unicode
142 0xFFFD REPLACEMENT CHARACTER code. Event type metrics are not current‐
143 ly supported.
144
145
146 INSTANCE DOMAINS METADATA: pmGetInDom, pmNameInDom, pmLookupInDom
147 The general form of the requests is as follows:
148
149 /pmapi/NNNN/_indom?indom=DDDD
150 List instances of the given instance domain.
151
152 /pmapi/NNNN/_indom?name=NAME
153 List instances of the instance domain belonging to the named
154 metric.
155
156 In addition, either query may be suffixed with:
157
158 &instance=IIII,JJJJ
159 Restrict listings to given instance code numbers.
160
161 &iname=INAME1,INAME2
162 Restrict listings to given instance names.
163
164 The response is a JSON document that provides the metric metadata as an
165 array. For example:
166
167 { "indom":DDDD,
168 "instances": [
169 { "instance":IIII, "name":"INAME" }
170 ...
171 ] }
172
173
174 INSTANCE PROFILE: pmAddProfile, pmDelProfile
175 The general form of these requests is as follows:
176
177 /pmapi/NNNN/_profile_reset?indom=DDDD
178 These are not currently supported.
179
180 /pmapi/NNNN/_profile_add?indom=DDDD&instance=IIII,JJJJ
181 These are not currently supported.
182
183 /pmapi/NNNN/_profile_add?indom=DDDD&iname=IIII,JJJJ
184 These are not currently supported.
185
186 /pmapi/NNNN/_profile_del?indom=DDDD&instance=JJJJ
187 These are not currently supported.
188
189 /pmapi/NNNN/_profile_del?indom=DDDD&iname=INAME1,INAME2
190 These are not currently supported.
191
192
193 METRIC STORE: pmStore
194 The general form of these requests is as follows:
195
196 /pmapi/NNNN/_store?name=NAME&value=VALUE
197 Store a new value for given named metrics.
198
199 /pmapi/NNNNN/_store?pmid=PPPP&value=VALUE
200 Store a new value for given performance metric identifier
201 (PMID).
202
203 In addition, either query may be suffixed with:
204
205 &instance=IIII,JJJJ
206 Restrict store to given instance code numbers.
207
208 &iname=INAME1,INAME2
209 Restrict store to given instance names.
210
211 If successful, the response from these requests is a JSON document of
212 the form:
213
214 { "success" : true }
215
216
217 DERIVED METRICS: pmRegisterDerived
218 /pmapi/NNNNN/_derive?name=NAME&expr=EXPRESSION
219 These are not currently supported.
220
221
222 CONTEXT COPY: pmDupContext
223 /pmapi/NNNNN/copy
224 These are not currently supported.
225
226
227 CONTEXT CLOSE: pmDestroyContext
228 /pmapi/NNNNN/destroy
229 This is not likely to be supported, as it is destructive and
230 would offer a tempting target to brute-force attackers. In‐
231 stead, the pmwebd timeout is used to automatically free unused
232 contexts.
233
234
235 PROMETHEUS
236 Prometheus exporting of live metrics from a preexisting PMWEBAPI con‐
237 text is available:
238
239 The general form of the requests is:
240
241 /pmapi/NNNNN/metrics?target=NAME1,NAME2,...
242 Fetch current values for given named metrics.
243
244 For all numeric metrics with the given NAME prefixes, create a
245 prometheus text export format giving their current value and related
246 metadata. The response has text/plain type rather than JSON, and is
247 designed to be ingested by a Prometheus server, or pcp's own pm‐
248 daprometheus.
249
250 The native PCP metric metadata (metric name, semantics and units) are
251 first output with the # PCP prefix. If the units string is empty, then
252 none is output. The units metadata string may contain spaces and ex‐
253 tends to the end of the line. Prometheus metric types are heuristical‐
254 ly inferred from PCP metric types, and units/scales are converted to
255 base seconds/bytes/count if possible, with a corresponding suffix added
256 to the metric name. PCP metric names are mapped so that . are ex‐
257 changed with :. Instance domain instances are represented as
258 Prometheus labels with quoted instance names.
259
260 # PCP proc.nprocs instant none
261 # HELP proc:nprocs instantaneous number of processes
262 # TYPE proc:nprocs gauge
263 proc:nprocs 7
264
265 # PCP kernel.pernode.cpu.intr counter millisec
266 # HELP kernel:pernode:cpu:intr_seconds_total total interrupt CPU time from /proc/stat for each node
267 # TYPE kernel:pernode:cpu:intr_seconds_total counter
268 kernel:pernode:cpu:intr_seconds_total{instance="node0"} 25603.540000000001
269
270 # PCP filesys.blocksize instant byte
271 # HELP filesys:blocksize_bytes Size of each block on mounted filesystem (Bytes)
272 # TYPE filesys:blocksize_bytes gauge
273 filesys:blocksize_bytes{instance="/dev/mapper/docker-253:0-83713-\
274 9a130460b46163fcf4443710db3159dea6bb5ec2aaca108515839a7a28c191ce"} 4096
275 filesys:blocksize_bytes{instance="/dev/mapper/VolGroup00-root17"} 4096
276
277
278
280 When enabled, pmwebd can emulate a subset of the graphite web-api to
281 allow web applications like graphite and grafana to extract data from
282 all archives under the configured -A directory. The graphite namespace
283 is constructed from the PCP archives using a simple mapping that en‐
284 codes the Cartesian product of archives, metrics, and instance-domain
285 instances into dot-separated strings. Some metacharacter-quoting is
286 employed to encode general strings into components. Only numeric PCP
287 metrics are exposed; COUNTER semantic values are rate-converted.
288
289
290 ┌─────────┬────────┬───────────────────────────────────────────────────────┐
291 │position │ number │ purpose │
292 ├─────────┼────────┼───────────────────────────────────────────────────────┤
293 │ 1 │ 1 │ encoded pathname of the archive .meta file (default), │
294 │ │ │ or canonicalized archive hostname (-J mode) │
295 │ 2 │ N │ the N components of the pcp metric name │
296 │ N+2 │ 1 │ instance name of the metric (if any) │
297 └─────────┴────────┴───────────────────────────────────────────────────────┘
298 Since glob wildcarding is supported within metric name components, us‐
299 ing them in the first component (an encoding of the archive name) is a
300 good way to identify machines, or to match multiple archives spanning
301 times of interest.
302
303 We list here only the broadest outline of the supported calls. pmwebd
304 does not support every graphite web-api option, so many querystring pa‐
305 rameters may be ignored. Arithmetic/statistical functions on metrics
306 are not supported.
307
308
309 /graphite/render?format=json&target=FOO&from=TIME&until=TIME
310 Return a series of values of the given metrics, between the two
311 times, sampled every 60 seconds.
312
313 /graphite/rawdata?target=FOO.BAR&from=TIME&until=TIME
314 Same, with a slightly different result encoding.
315
316 /graphite/render?format=png&target=FOO&from=TIME&until=TIME&....
317 Same, but render the curves into a PNG image file. Several col‐
318 or- and rendering-control-related parameters are supported.
319
320 /graphite/metrics/find?query=FOO.BAR.*
321 Provide incremental metric-tree traversal using wildcards.
322
323 /graphite/graphlot/findmetric?query=FOO+BAR
324 Search through metrics with space-separated regular expressions.
325
326 /graphite/browser/search?q=FOO+BAR
327 Same, with a slightly different result encoding.
328
329
330
332 PCPIntro(1), PCPIntro(3), pmwebd(1), http://graphite.readthedocs.org/
333 and PMAPI(3)
334
335
336
337Performance Co-Pilot PCP PMWEBAPI(3)