1PMWEBAPI(3) Library Functions Manual PMWEBAPI(3)
2
6 PMWEBAPI - introduction to the Performance Metrics Web Application Pro‐
7 gramming Interface
8
10 GET /metrics
11 GET /series/...
12 GET /search/...
13 GET /pmapi/...
14
16 #include <pcp/pmwebapi.h>
17 ... assorted routines ...
19 cc ... -lpcp_web -lpcp
21
23 The PMWEBAPI is a collection of interfaces providing Performance Co-Pi‐
24 lot services for web applications. It consists of APIs for web appli‐
25 cations querying and analysing both live and historical performance
26 data, as well as APIs used by web servers.
27 The usual HTTP URL-encoded optional parameter rules apply and PMWEBAPI
29 REST requests always follow the convention:
30 /api/endpoint?parameter1=value1¶meter2=value2
32 Examples in all following sections use the curl(1) command line utility
34 with a local pmproxy(1) server listening on port 44322 (default port).
35 The pmjson(1) utility is used to neatly format any JSON output, as op‐
36 posed to the compact (minimal whitespace) form provided by default.
37 The examples in the scalable time series section use historical data
38 recorded by the pmlogger(1) service, in conjunction with a local redis-
39 server(1).
40
42 Exporting of live performance metrics in an Open Metrics compatible
43 format (as described at https://openmetrics.io and popularized by the
44 https://prometheus.io project) is available.
45 All requests are performed on the web server host by default, unless a
47 hostspec parameter is provided.
48 GET /metrics
50 ┌───────────┬─────────┬────────────────────────────────────────────────┐
51 │Parameters │ Type │ Explanation │
52 ├───────────┼─────────┼────────────────────────────────────────────────┤
53 │names │ string │ Comma-separated list of metric names │
54 │times │ boolean │ Append sample times (milliseconds since epoch) │
55 ├───────────┼─────────┼────────────────────────────────────────────────┤
56 │hostspec │ string │ Host specification as described in PCPIntro(1) │
57 └───────────┴─────────┴────────────────────────────────────────────────┘
58 Fetches current values and metadata for all metrics, or only metrics
59 indicated by a comma-separated list of names.
60 For all numeric metrics with the given NAME prefixes, create an Open
62 Metrics (Prometheus) text export format giving their current value and
63 related metadata.
64 The response has plain text type rather than JSON commonly used else‐
66 where in the REST API. This format can be injested by many open source
67 monitoring tools, including Prometheus and pmdaopenmetrics(1).
68 The native PCP metric metadata (metric name, type, indom, semantics and
70 units) is first output for each metric with # PCP prefix. The metadata
71 reported is of the form described on pmTypeStr(3), pmInDomStr(3), pm‐
72 SemStr(3) and pmUnitsStr(3) respectively. If the pmUnitsStr(3) units
73 string is empty, then none is output. The units metadata string may
74 contain spaces and extends to the end of the line.
75 PCP metric names are mapped so that the . separators are exchanged with
77 _ (':' in back-compatibility mode, where "# PCP" is the identifying
78 line suffix). Both metric labels and instances are represented as
79 Prometheus labels, with external instance names being quoted and the
80 flattened PCP metric hierarchy being presented with each value.
81 $ curl -s http://localhost:44322/metrics?names=proc.nprocs,kernel.pernode.cpu.intr,filesys.blocksize
83 # PCP5 proc.nprocs 3.8.99 u32 PM_INDOM_NULL instant none
85 # HELP proc_nprocs instantaneous number of processes
86 # TYPE proc_nprocs gauge
87 proc_nprocs {hostname="app1"} 7
88 # PCP5 kernel.pernode.cpu.intr 60.0.66 u64 60.19 counter millisec
90 # HELP kernel_pernode_cpu_intr total interrupt CPU [...]
91 # TYPE kernel_pernode_cpu_intr counter
92 kernel_pernode_cpu_intr{hostname="app1",instname="node0"} 25603
93 # PCP5 filesys.blocksize 60.5.9 u32 60.5 instant byte
95 # HELP filesys_blocksize Size of each block on mounted file[...]
96 # TYPE filesys_blocksize gauge
97 filesys_blocksize{hostname="app1",instname="/dev/sda1"} 4096
98 filesys_blocksize{hostname="app1",instname="/dev/sda2"} 4096
99
101 The fast, scalable time series query capabilities provided by the pm‐
102 series(1) command are also available through a REST API. These queries
103 provide access to performance data (metric metadata and values) from
104 multiple hosts simultaneously, and in a fashion suited to efficient re‐
105 trieval by any number of web applications.
106 All requests in this group can be accompanied by an optional client pa‐
108 rameter. The value passed in the request will be sent back in the re‐
109 sponse - all responses will be in JSON object form in this case, with
110 top level "client" and "result" fields.
111 REST API clients can optionally submit an URL-encoded query string in
113 the body of the HTTP request unless otherwise noted. In this case the
114 POST method must be used instead of the GET method.
115 GET /series/query - pmSeriesQuery(3)
117 ┌───────────┬────────┬────────────────────────────────────────────┐
118 │Parameters │ Type │ Explanation │
119 ├───────────┼────────┼────────────────────────────────────────────┤
120 │expr │ string │ Query string in pmseries(1) format │
121 │client │ string │ Request identifier sent back with response │
122 └───────────┴────────┴────────────────────────────────────────────┘
123 Performs a time series query for either matching identifiers, or match‐
124 ing identifiers with series of time-stamped values.
125 The query is in the format described in pmseries(1) and is passed to
127 the server via either the expr parameter (HTTP GET) or via the message
128 body (HTTP POST).
129 When querying for time series matches only, no time window options are
131 specified and matching series identifiers are returned in a JSON array.
132 $ curl -s 'http://localhost:44322/series/query?expr=disk.dev.read*' | pmjson
134 [
135 "9d8c7fb51ce160eb82e3669aac74ba675dfa8900",
136 "ddff1bfe286a3b18cebcbadc1678a68a964fbe9d",
137 "605fc77742cd0317597291329561ac4e50c0dd12"
138 ]
139 When querying for time series values as well, a time window must be
141 specified as part of the query string. The simplest form is to just
142 request the most recent sample.
143 $ curl -s 'http://localhost:44322/series/query?expr=disk.dev.read*[samples:1]' | pmjson
145 [
146 {
147 "series": "9d8c7fb51ce160eb82e3669aac74ba675dfa8900",
148 "instance": "c3795d8b757506a2901c6b08b489ba56cae7f0d4",
149 "timestamp": 1547483646.2147431,
150 "value": "12499"
151 }, {
152 "series": "ddff1bfe286a3b18cebcbadc1678a68a964fbe9d",
153 "instance": "6b08b489ba56cae7f0d4c3795d8b757506a2901c",
154 "timestamp": 1547485701.7431218,
155 "value": "1118623"
156 }, {
157 "series": "605fc77742cd0317597291329561ac4e50c0dd12",
158 "instance": "c3795d8b757506a2901c6b08b489ba56cae7f0d4",
159 "timestamp": 1547483646.2147431,
160 "value": "71661"
161 }
162 ]
163 GET /series/values - pmSeriesValues(3)
165 ┌───────────┬────────┬────────────────────────────────────────────┐
166 │Parameters │ Type │ Explanation │
167 ├───────────┼────────┼────────────────────────────────────────────┤
168 │series │ string │ Comma-separated list of series identifiers │
169 │client │ string │ Request identifier sent back with response │
170 ├───────────┼────────┼────────────────────────────────────────────┤
171 │samples │ number │ Count of samples to return │
172 │interval │ string │ Time between successive samples │
173 │start │ string │ Sample window start time │
174 │finish │ string │ Sample window end time │
175 │offset │ string │ Sample window offset │
176 │align │ string │ Sample time alignment │
177 │zone │ string │ Time window timezone │
178 └───────────┴────────┴────────────────────────────────────────────┘
179 Performs values retrievals for one or more time series identifiers.
180 The JSON response contains the same information as the pmseries
181 -q/--query option using any of the time window parameters described on
182 pmseries(1). If no time window parameters are specified, the single
183 most recent value observed is retrieved.
184 $ curl -s http://localhost:44322/series/values?series=605fc77742cd0317597291329561ac4e50c0dd12 | pmjson
186 [
187 {
188 "series": "605fc77742cd0317597291329561ac4e50c0dd12",
189 "timestamp": 1317633022959.959241041,
190 "value": "71660"
191 }
192 ]
193 GET /series/descs - pmSeriesDescs(3)
195 ┌───────────┬────────┬────────────────────────────────────────────┐
196 │Parameters │ Type │ Explanation │
197 ├───────────┼────────┼────────────────────────────────────────────┤
198 │series │ string │ Comma-separated list of series identifiers │
199 │client │ string │ Request identifier sent back with response │
200 └───────────┴────────┴────────────────────────────────────────────┘
201 Performs a descriptor lookup for one or more time series identifiers.
202 The JSON response contains the same information as the pmseries
203 -d/--desc option.
204 $ curl -s http://localhost:44322/series/descs?series=605fc77742cd0317597291329561ac4e50c0dd12 | pmjson
206 [
207 {
208 "series": "605fc77742cd0317597291329561ac4e50c0dd12",
209 "source": "f5ca7481da8c038325d15612bb1c6473ce1ef16f",
210 "pmid": "60.0.4",
211 "indom": "60.1",
212 "semantics": "counter",
213 "type": "u32",
214 "units": "count",
215 }
216 ]
217 GET /series/labels - pmSeriesLabels(3), pmSeriesLabelValues(3)
219 ┌───────────┬────────┬────────────────────────────────────────────┐
220 │Parameters │ Type │ Explanation │
221 ├───────────┼────────┼────────────────────────────────────────────┤
222 │series │ string │ Comma-separated list of series identifiers │
223 │match │ string │ Glob pattern string to match on all labels │
224 │name │ string │ Find all known label values for given name │
225 │names │ string │ Comma-separated list of label names │
226 │client │ string │ Request identifier sent back with response │
227 └───────────┴────────┴────────────────────────────────────────────┘
228 This command operates in one of three modes. It can perform a label
229 set lookup for one or more time series identifiers, when given the
230 series parameter). It can produce a list of all known label names, in
231 the absence of name, names or series parameters. The JSON responses
232 for these modes contains the same information as the pmseries
233 -l/--labels option.
234 Alternatively, it can produce a list of all known label values for a
236 given label name or names. The JSON response for this mode contains
237 the same information as the pmseries -v/--values option.
238 $ curl -s http://localhost:44322/series/labels?series=605fc77742cd0317597291329561ac4e50c0dd12 | pmjson
240 [
241 {
242 "series": "605fc77742cd0317597291329561ac4e50c0dd12",
243 "labels": {
244 "agent": "linux",
245 "domainname": "acme.com",
246 "groupid": 1000,
247 "hostname": "www.acme.com",
248 "latitude": -25.28496,
249 "longitude": 152.87886,
250 "machineid": "295b16e3b6074cc8bdbda8bf96f6930a",
251 "platform": "dev",
252 "userid": 1000
253 }
254 }
255 ]
256 Alternatively, with no name, names or series parameters, return the
258 list of all known label names.
259 $ curl -s http://localhost:44322/series/labels | pmjson
261 [
262 "agent",
263 "appversion",
264 "domainname",
265 "groupid",
266 "hostname",
267 "jobid",
268 "latitude",
269 "longitude",
270 "machineid",
271 "platform",
272 "userid"
273 ]
274 Use the name or names parameters to find all possible label values for
276 the given name(s).
277 $ curl -s http://localhost:44322/series/labels?names=hostname,domainname | pmjson
279 {
280 "hostname": [ "app", "nas" ],
281 "domainname": [ "acme.com" ]
282 }
283 GET /series/metrics - pmSeriesMetrics(3)
285 ┌───────────┬────────┬────────────────────────────────────────────┐
286 │Parameters │ Type │ Explanation │
287 ├───────────┼────────┼────────────────────────────────────────────┤
288 │series │ string │ Comma-separated list of series identifiers │
289 │match │ string │ Glob pattern string to match on all names │
290 │client │ string │ Request identifier sent back with response │
291 └───────────┴────────┴────────────────────────────────────────────┘
292 Performs a metric name lookup for one or more time series identifiers.
293 The JSON response contains the same information as the pmseries
294 -m/--metrics option.
295 $ curl -s http://localhost:44322/series/metrics?series=605fc77742cd0317597291329561ac4e50c0dd12 | pmjson
297 [
298 {
299 "series": "605fc77742cd0317597291329561ac4e50c0dd12",
300 "name": "disk.dev.read_bytes"
301 }
302 ]
303 Alternatively, with no series argument, this request will return the
305 list of all known metric names.
306 $ curl -s http://localhost:44322/series/metrics | pmjson
308 [
309 "disk.dev.read",
310 "disk.dev.read_bytes",
311 "disk.dev.read_merge",
312 "kernel.all.load",
313 "kernel.all.pswitch",
314 ...
315 ]
316 GET /series/sources - pmSeriesSources(3)
318 ┌───────────┬────────┬─────────────────────────────────────────────┐
319 │Parameters │ Type │ Explanation │
320 ├───────────┼────────┼─────────────────────────────────────────────┤
321 │series │ string │ Comma-separated list of source identifiers │
322 │match │ string │ Glob pattern string to match on all sources │
323 │client │ string │ Request identifier sent back with response │
324 └───────────┴────────┴─────────────────────────────────────────────┘
325 Performs a lookup for one or more time series sources, returning an ar‐
326 ray of all PMAPI context names used to access the time series from that
327 source. The JSON response contains the same information as the pm‐
328 series -S/--source option.
329 $ curl -s http://localhost:44322/series/sources?source=2cd6a38f9339f2dd1f0b4775bda89a9e7244def6 | pmjson
331 [
332 {
333 "source": "2cd6a38f9339f2dd1f0b4775bda89a9e7244def6",
334 "context": [
335 "/var/log/pcp/pmlogger/acme",
336 "www.acme.com"
337 ]
338 }
339 ]
340 GET /series/instances - pmSeriesInstances(3)
342 ┌───────────┬────────┬───────────────────────────────────────────────┐
343 │Parameters │ Type │ Explanation │
344 ├───────────┼────────┼───────────────────────────────────────────────┤
345 │series │ string │ Comma-separated list of series identifiers │
346 │match │ string │ Glob pattern string to match on all instances │
347 │client │ string │ Request identifier sent back with response │
348 └───────────┴────────┴───────────────────────────────────────────────┘
349 Provide instance identifiers and names for one or more time series
350 identifiers. The JSON response contains the same information as the
351 pmseries -i/--instance option.
352 $ curl -s http://localhost:44322/series/instances?series=605fc77742cd0317597291329561ac4e50c0dd12 | pmjson
354 [
355 {
356 "series": "605fc77742cd0317597291329561ac4e50c0dd12",
357 "source": "97261ac7742cd4e50c0d03175913295d12605fc7",
358 "instance": "c3795d8b757506a2901c6b08b489ba56cae7f0d4"
359 "id": 1,
360 "name": "sda",
361 }, {
362 "series": "605fc77742cd0317597291329561ac4e50c0dd12",
363 "source": "97261ac7742cd4e50c0d03175913295d12605fc7",
364 "instance": "57506a2901c6b08b489ba56cae7f0d4c3795d8b7"
365 "id": 2,
366 "name": "sdb",
367 }
368 ]
369 Alternatively, with no series argument, this request will return the
371 list of all known instance names.
372 $ curl -s http://localhost:44322/series/instances | pmjson
374 [
375 "1 minute",
376 "5 minute",
377 "15 minute",
378 "cpu0",
379 "cpu1",
380 "cpu2",
381 "cpu3",
382 "node0",
383 "node1",
384 "sda",
385 "sdb",
386 ...
387 ]
388 GET /series/load - pmSeriesLoad(3)
390 ┌───────────┬────────┬────────────────────────────────────────────┐
391 │Parameters │ Type │ Explanation │
392 ├───────────┼────────┼────────────────────────────────────────────┤
393 │expr │ string │ Source load string in pmseries(1) format │
394 │client │ string │ Request identifier sent back with response │
395 └───────────┴────────┴────────────────────────────────────────────┘
396 Load time series performance data from the specified source into the
397 redis-server cache. This request is equivalent to the pmseries
398 -l/--load option.
399 $ curl -s http://localhost:44322/series/load?expr={source.name:"/var/log/pcp/pmlogger/acme"}
401 {
402 "success": true
403 }
404
406 The full text search capabilities provided by the pmsearch(1) command
407 are also available through a REST API. These queries provide access to
408 an index over performance metric names, instances, instance domains and
409 help text, suitable for a metric search engine, and in a fashion suited
410 to efficient querying by any number of web applications.
411 In order to use this functionality, the optional RediSearch module must
413 be loaded in the redis-server at the time pmproxy is started, such that
414 metrics, instances and help text it discovers can be automatically in‐
415 dexed.
416 GET /search/text - pmSearchTextQuery(3)
419 ┌───────────┬────────┬─────────────────────────────────────────────┐
420 │Parameters │ Type │ Explanation │
421 ├───────────┼────────┼─────────────────────────────────────────────┤
422 │query │ string │ Query string in pmsearch(1) format │
423 │highlight │ fields │ Include matching markup in response fields │
424 │offset │ number │ Result offset cursor for pagination │
425 │limit │ number │ Maximum results to include in response │
426 │field │ fields │ Queried fields (defaults to all) │
427 │return │ fields │ Fields to actually return (defaults to all) │
428 │type │ types │ Entity types to filter (defaults to all) │
429 └───────────┴────────┴─────────────────────────────────────────────┘
430 Performs a text search query across metrics and instance domains - all
431 forms of names and help texts.
432 The mandatory search string is further described in pmsearch(1) and is
434 passed to the server via the query parameter (HTTP GET).
435 $ curl -s http://localhost:44322/search/text?query=halt | pmjson
437 {
438 "total": 2,
439 "offset": 0,
440 "limit": 10,
441 "elapsed": 0.000504,
442 "results": [
443 {
444 "name": "kvm.halt_exits",
445 "type": "metric",
446 "indom": "95.0.4",
447 "oneline": "Number of guest exits due to halt calls.",
448 "helptext": "This type of exit is usually seen when a guest is idle."
449 },
450 {
451 "name": "kvm.halt_wakeup",
452 "type": "metric",
453 "indom": "95.0.6",
454 "oneline": "Number of wakeups from a halt.",
455 }
456 ]
457 }
458 The available search entity types are metric, indom and instance.
460 Query parameters highlight and field take name, oneline and helptext.
461 Query parameter return takes name, type, oneline, helptext, indom.
463 There is typically both a name and help text associated with metrics.
464 Contents of these are then matched against query. An instance domain
465 has help text and a numeric identifier, while instances have a name on‐
466 ly (which can be searched).
467 GET /search/suggest - pmSearchTextSuggest(3)
469 ┌───────────┬────────┬────────────────────────────────────┐
470 │Parameters │ Type │ Explanation │
471 ├───────────┼────────┼────────────────────────────────────┤
472 │query │ string │ Search query for search engine │
473 │limit │ number │ Max results to include in response │
474 └───────────┴────────┴────────────────────────────────────┘
475 Provides search query suggestions, that is, metric and instance names.
476 The mandatory search string is further described in pmsearch(1) and is
478 passed to the server via the query parameter (HTTP GET).
479 $ curl -s http://localhost:44322/search/suggest?query=disk&limit=4 | pmjson
481 [
482 "disk.all.avactive",
483 "disk.all.aveq",
484 "disk.all.blkread",
485 "disk.all.blktotal"
486 ]
487 GET /search/indom - pmSearchTextInDom(3)
489 ┌───────────┬────────┬─────────────────────────────────────┐
490 │Parameters │ Type │ Explanation │
491 ├───────────┼────────┼─────────────────────────────────────┤
492 │query │ string │ Target indom for search engine │
493 │offset │ number │ Result offset cursor for pagination │
494 │limit │ number │ M results to include in response │
495 └───────────┴────────┴─────────────────────────────────────┘
496 Provides all entities (instances, metrics) related to indom, including
497 itself, that is passed to the server via the query parameter.
498 GET /search/info - pmSearchInfo(3)
500 Provides metrics relating to operation of the search engine, in partic‐
501 ular showing document and text record counts.
502 $ curl -s http://localhost:44322/search/info | pmjson
504 {
505 "docs": 1589,
506 "terms": 3855,
507 "records": 116831,
508 "records_per_doc_avg": 73.52,
509 "bytes_per_record_avg": 6.36,
510 "inverted_sz_mb": 0.71,
511 "inverted_cap_mb": 0.00,
512 "inverted_cap_ovh": 0.00,
513 "skip_index_size_mb": 0.00,
514 "score_index_size_mb": 0.00,
515 "offsets_per_term_avg": 9.41,
516 "offset_bits_per_record_avg": 8.00
517 }
518
520 The live performance collection facilities available from pmcd(1) can
521 also be accessed through a REST API.
522 All requests are performed on the web server host by default, unless
524 either a hostspec or context parameter is provided. hostname can be
525 used in place of hostspec.
526 Context identifiers are used as a persistent way to refer to PMAPI con‐
528 texts across related web requests. These contexts expire after a con‐
529 figurable period of disuse, and are either explicitly allocated using
530 the /pmapi/context interface, or implicitly allocated using other in‐
531 terfaces.
532 The timeout interval is configurable at context creation time, and as
534 such the polltimeout parameter can be used anywhere the hostspec is
535 specified. It sets the context timeout in terms of length of inactive
536 time. The unit for the timeout value is seconds and the default is 5.
537 To specify a specific existing context in any PMAPI web request, the
539 endpoints can be accessed with either the context parameter or embedded
540 in the endpoint URL itself, such as /pmapi/[number]/fetch.
541 GET /pmapi/context - pmNewContext(3)
543 ┌────────────┬────────┬────────────────────────────────────────────────┐
544 │Parameters │ Type │ Explanation │
545 ├────────────┼────────┼────────────────────────────────────────────────┤
546 │hostspec │ string │ Host specification as described in PCPIntro(1) │
547 │polltimeout │ number │ Seconds of inactivity before closing context │
548 │client │ string │ Request identifier sent back with response │
549 └────────────┴────────┴────────────────────────────────────────────────┘
550 To create a context for live sampling, a web client can access any
551 /pmapi URL (optionally using the hostspec or context parameter). If no
552 context exists, a new one will be created for that web client, and its
553 identifier returned for future accesses.
554 However, /pmapi/context is provided as a dedicated URL for applications
556 wishing to explicitly create the contexts they use.
557 If successful, the server responds with a HTTP 200 (OK) code and JSON
559 message body of the form:
560 $ curl -s http://localhost:44322/pmapi/context?hostspec=www.acme.com&polltimeout=0.5 | pmjson
562 {
563 "context": 348734,
564 "source": "05af7f3eb840277fd3cfa91f90ef0067199743c",
565 "hostspec": "www.acme.com",
566 "labels": {
567 "domainname": "acme.com",
568 "groupid": 1000,
569 "hostname": "www.acme.com",
570 "machineid": "295b7623b6074cc8bdbda8bf96f6930a"
571 "platform": "dev",
572 "userid": 1000
573 }
574 }
575 The context (a 32-bit unsigned decimal number) can then be used with
577 all later requests.
578 In the case of a hostspec containing authentication information, such
580 as a username, the server will follow the HTTP Basic Authentication
581 protocol to ascertain necessary authentication details from the user,
582 providing the client web application an opportunity to request these
583 from the user.
584 GET /pmapi/metric - pmLookupDesc(3), pmLookupLabels(3), pmLookupName(3),
586 pmLookupText(3)
587 ┌────────────┬────────┬────────────────────────────────────────────────┐
588 │Parameters │ Type │ Explanation │
589 ├────────────┼────────┼────────────────────────────────────────────────┤
590 │name │ string │ An individual metric name │
591 │names │ string │ Comma-separated list of metric names │
592 │pmid │ pmID │ Numeric or pmIDStr(3) metric identifier │
593 │pmids │ string │ Comma-separated numeric or pmIDStr(3) pmIDs │
594 │prefix │ string │ Metric namespace component as in PMNS(5) │
595 ├────────────┼────────┼────────────────────────────────────────────────┤
596 │hostspec │ string │ Host specification as described in PCPIntro(1) │
597 │context │ number │ Web context number (optional like hostspec) │
598 │polltimeout │ number │ Seconds of inactivity before context closed │
599 │client │ string │ Request identifier sent back with response │
600 └────────────┴────────┴────────────────────────────────────────────────┘
601 The metric endpoint provides detailed PMAPI metric metadata for one or
602 more metrics. If no parameters are supplied, the response will be for
603 all metrics found when traversing the entire Performance Metrics Name
604 Space (PMNS).
605 The prefix parameter can be used to specify a subtree of the PMNS for
607 traversal. Alternatively, a specific metric or comma-separated list of
608 metrics can be specified using either name or names
609 The server response is a JSON document that provides metric metadata as
611 an array.
612 $ curl -s http://localhost:44322/pmapi/metric?names=kernel.all.load,disk.all.read | pmjson
614 {
615 "context": 348734,
616 "metrics": [
617 {
618 "name": "kernel.all.load",
619 "pmid": "60.2.0",
620 "indom": "60.2",
621 "type": "FLOAT",
622 "sem": "instant",
623 "units": "none",
624 "series": "d2b28c7f6dc0d69ffd21dba7ba955e78c37719b",
625 "source": "05af7f3eb840277fd3cfa91f90ef0067199743c",
626 "labels": {
627 "agent": "linux",
628 "domainname": "acme.com",
629 "groupid": 1000,
630 "hostname": "www.acme.com",
631 "platform": "dev",
632 "userid": 1000
633 },
634 "text-oneline": "1, 5 and 15 minute load average"
635 },
636 {
637 "name": "disk.all.read",
638 "pmid": "60.0.24",
639 "type": "U64",
640 "sem": "counter",
641 "units": "count",
642 "series": "d2b28c7f6dc0d69ffd21dba7ba955e78c37719b",
643 "source": "05af7f3eb840277fd3cfa91f90ef0067199743c",
644 "labels": {
645 "agent": "linux",
646 "domainname": "acme.com",
647 "groupid": 1000,
648 "hostname": "www.acme.com",
649 "platform": "dev",
650 "userid": 1000
651 },
652 "text-oneline": "total read operations, summed for all disks",
653 "text-help": "Cumulative number of disk read operations [...]"
654 }
655 ]
656 }
657 Most of the fields are directly transcribed from the PMAPI calls for
658 metric descriptors, labels and help text mentioned above and are exact‐
659 ly as would be observed using the pminfo(1) command with the -dlmstT
660 options.
661 The semantics, type and units fields are as returned by pmTypeStr(3),
663 pmUnitsStr(3) and pmSemStr(3).
664 GET /pmapi/fetch - pmFetch(3)
666 ┌────────────┬────────┬────────────────────────────────────────────────┐
667 │Parameters │ Type │ Explanation │
668 ├────────────┼────────┼────────────────────────────────────────────────┤
669 │delta │ string │ Sampling interval in pmParseInterval(3) form │
670 │name │ string │ An individual metric name │
671 │names │ string │ Comma-separated list of metric names │
672 │pmid │ pmID │ Numeric or pmIDStr(3) metric identifier │
673 │pmids │ string │ Comma-separated numeric or pmIDStr(3) pmIDs │
674 ├────────────┼────────┼────────────────────────────────────────────────┤
675 │hostspec │ string │ Host specification as described in PCPIntro(1) │
676 │context │ number │ Web context number (optional like hostspec) │
677 │polltimeout │ number │ Seconds of inactivity before context closed │
678 │client │ string │ Request identifier sent back with response │
679 └────────────┴────────┴────────────────────────────────────────────────┘
680 This request fetches (samples) current values for given metrics.
681 If any of the names or pmids provided are valid, the response is a JSON
683 document that provides the values for all instances of the metrics, un‐
684 less a instance profile has been set for the web context (see section
685 on InDom profiles below).
686 $ curl -s http://localhost:44322/pmapi/fetch?names=kernel.all.load,disk.all.read | pmjson
688 {
689 "context": 348734,
690 "timestamp": 1547483646.2147431,
691 "values": [
692 {
693 "pmid": "60.2.0",
694 "name": "kernel.all.load",
695 "instances:" [
696 { "instance": 1, "value": 0.1 },
697 { "instance": 5, "value": 0.17 },
698 { "instance": 15, "value": 0.22 }
699 ]
700 },
701 {
702 "pmid":"60.0.24",
703 "name":"disk.all.read",
704 "instances:" [
705 { "instance": null, "value": 639231 }
706 ]
707 }
708 ]
709 }
710 The response fields map directly to fields from the underlying pm‐
711 Fetch(3) sampling interface.
712 Numeric metric types are represented as JSON integer or floating-point
714 values. Strings are passed verbatim, except that non-ASCII values are
715 replaced with a Unicode 0xFFFD replacement character code.
716 In backward compatibility mode the timestamp is presented as a JSON map
718 with second (sec) and microsecond (us) fields, instead of using the
719 more compact floating point representation shown above.
720 GET /pmapi/children - pmGetChildren(3), pmGetChildrenStatus(3)
722 ┌────────────┬────────┬────────────────────────────────────────────────┐
723 │Parameters │ Type │ Explanation │
724 ├────────────┼────────┼────────────────────────────────────────────────┤
725 │prefix │ string │ Metric namespace component as in PMNS(5) │
726 ├────────────┼────────┼────────────────────────────────────────────────┤
727 │hostspec │ string │ Host specification as described in PCPIntro(1) │
728 │context │ number │ Web context number (optional like hostspec) │
729 │polltimeout │ number │ Seconds of inactivity before context closed │
730 │client │ string │ Request identifier sent back with response │
731 └────────────┴────────┴────────────────────────────────────────────────┘
732 The children endpoint provides iterative namespace traversal for a con‐
733 text. If no parameters are supplied, the response will describe the
734 direct descendants of the Performance Metrics Name Space (PMNS) root.
735 The prefix parameter can be used to specify a subtree of the PMNS for
737 traversal.
738 The server response is a JSON document that provides the set of leaf
740 and non-leaf nodes below the given namespace node or root.
741 $ curl -s http://localhost:44322/pmapi/children?prefix=mem | pmjson
743 {
744 "context": 348734,
745 "name": "mem",
746 "leaf": [
747 "physmem",
748 "freemem"
749 ],
750 "nonleaf": [
751 "util",
752 "numa",
753 "vmstat",
754 "buddyinfo",
755 "slabinfo",
756 "zoneinfo",
757 "ksm"
758 ]
759 }
760 GET /pmapi/indom - pmGetInDom(3), pmNameInDom(3), pmLookupInDom(3)
762 ┌────────────┬─────────┬────────────────────────────────────────────────┐
763 │Parameters │ Type │ Explanation │
764 ├────────────┼─────────┼────────────────────────────────────────────────┤
765 │iname │ string │ Comma-separated list of instance names │
766 │indom │ pmInDom │ Numeric or pmInDomStr(3) instance domain │
767 │instance │ number │ Comma-separated list of instance numbers │
768 │match │ string │ Pattern matching style (exact, glob or regex) │
769 │name │ string │ An individual metric name │
770 ├────────────┼─────────┼────────────────────────────────────────────────┤
771 │hostspec │ string │ Host specification as described in PCPIntro(1) │
772 │context │ number │ Web context number (optional like hostspec) │
773 │polltimeout │ number │ Seconds of inactivity before context closed │
774 │client │ string │ Request identifier sent back with response │
775 └────────────┴─────────┴────────────────────────────────────────────────┘
776 This request lists the current instances of an instance domain. The
777 instance domain is either specified directly (in numeric or string
778 form) or indirectly, by association with the specified metric.
779 The request can be further qualified with a comma-separated list of the
781 instances to report on, either by name or number, using the instance
782 and iname parameters.
783 In the case of instance name qualifiers, these will be matched by exact
785 string comparison by default. Alternatively, the match parameter can
786 be used to specify that regular expression or glob pattern matching
787 should be used instead.
788 The response is a JSON document that provides the instance domain meta‐
790 data as an array.
791 $ curl -s http://localhost:44322/pmapi/indom?name=kernel.all.load | pmjson
793 {
794 "context": 348734,
795 "indom": "60.2",
796 "labels": {
797 "domainname": "acme.com",
798 "groupid": 1000,
799 "hostname": "www.acme.com",
800 "machineid": "295b7623b6074cc8bdbda8bf96f6930a"
801 "platform": "dev",
802 "userid": 1000
803 },
804 "instances": [
805 {
806 "instance": 1,
807 "name": "1 minute"
808 "labels": { ... },
809 },
810 {
811 "instance": 5,
812 "name": "5 minute"
813 "labels": { ... },
814 },
815 {
816 "instance": 15,
817 "name": "15 minute"
818 "labels": { ... },
819 }
820 ]
821 }
822 GET /pmapi/profile - pmAddProfile(3), pmDelProfile(3)
824 ┌────────────┬─────────┬────────────────────────────────────────────────┐
825 │Parameters │ Type │ Explanation │
826 ├────────────┼─────────┼────────────────────────────────────────────────┤
827 │iname │ string │ Comma-separated list of instance names │
828 │indom │ pmInDom │ Numeric or pmInDomStr(3) instance domain │
829 │instance │ number │ Comma-separated list of instance numbers │
830 │expr │ string │ One of "add" or "del" (mandatory). │
831 │match │ string │ Pattern matching style (exact, glob or regex) │
832 ├────────────┼─────────┼────────────────────────────────────────────────┤
833 │hostspec │ string │ Host specification as described in PCPIntro(1) │
834 │context │ number │ Web context number (optional like hostspec) │
835 │polltimeout │ number │ Seconds of inactivity before context closed │
836 │client │ string │ Request identifier sent back with response │
837 └────────────┴─────────┴────────────────────────────────────────────────┘
838 Some PMAPI operations can be performed with an active instance domain
839 profile which restricts (filters) the set of resulting instances re‐
840 turned, as described on pmAddProfile(3).
841 $ curl -s http://localhost:44322/pmapi/profile?expr=add,indom=60.2,iname=1%20minute
843 { "context": 348734, "success": true }
844 GET /pmapi/store - pmStore(3)
846 ┌────────────┬────────┬────────────────────────────────────────────────┐
847 │Parameters │ Type │ Explanation │
848 ├────────────┼────────┼────────────────────────────────────────────────┤
849 │iname │ string │ Comma-separated list of instance names │
850 │instance │ number │ Comma-separated list of instance numbers │
851 │name │ string │ An individual metric name │
852 │value │ (any) │ New value for the given metric instance(s) │
853 ├────────────┼────────┼────────────────────────────────────────────────┤
854 │hostspec │ string │ Host specification as described in PCPIntro(1) │
855 │context │ number │ Web context number (optional like hostspec) │
856 │polltimeout │ number │ Seconds of inactivity before context closed │
857 │client │ string │ Request identifier sent back with response │
858 └────────────┴────────┴────────────────────────────────────────────────┘
859 Some performance metrics allow their value to be modified, for example
860 to re-initialize counters or to modify control variables.
861 This operation takes a single metric name to modify, and optionally
863 specific instances. The mandatory value will be interpreted according
864 to the type of the metric being modified.
865 If successful, the response from these requests is a JSON document of
867 the form:
868 $ curl -s http://localhost:44322/pmapi/store?name=pmcd.control.timeout&value=10
870 {
871 "context": 348734,
872 "success": true
873 }
874 GET /pmapi/derive: pmAddDerived(3)
876 ┌────────────┬────────┬────────────────────────────────────────────────┐
877 │Parameters │ Type │ Explanation │
878 ├────────────┼────────┼────────────────────────────────────────────────┤
879 │expr │ string │ Derived metric expression │
880 │name │ string │ New derived metric name │
881 ├────────────┼────────┼────────────────────────────────────────────────┤
882 │hostspec │ string │ Host specification as described in PCPIntro(1) │
883 │context │ number │ Web context number (optional like hostspec) │
884 │polltimeout │ number │ Seconds of inactivity before context closed │
885 │client │ string │ Request identifier sent back with response │
886 └────────────┴────────┴────────────────────────────────────────────────┘
887 Create a new derived metric, as defined by the pmAddDerived(3) metric
888 interface. Derived metrics are associated with the named context, or a
889 new context is created and returned in the result.
890 This interface is one of the few that allows a POST to be used in place
892 of a GET. In this case the HTTP POST request body may be used to pro‐
893 vide one or more derived metrics specifications (all at once, across
894 multiple lines, as a convenience).
895 $ curl -s http://localhost:44322/pmapi/derive?name=blkio.avgsz&expr=disk.all.blktotal/disk.all.total | pmjson
897 {
898 "context": 348734,
899 "success": true
900 }
901 $ curl -s http://localhost:44322/pmapi/fetch?name=blkio.avgsz&samples=2 | pmjson
903 {
904 "context": 348734,
905 "timestamp": 1547483648.2147428,
906 "values": [
907 {
908 "pmid": "511.0.27",
909 "name": "blkio.avgsz",
910 "instances:" [
911 {
912 "instance": null,
913 "value": 9231
914 }
915 ]
916 }
917 ]
918 }
919 GET /pmapi/metrics: pmLookupDesc(3),pmLookupLabels(3), pmFetch(3)
921 ┌────────────┬─────────┬────────────────────────────────────────────────┐
922 │Parameters │ Type │ Explanation │
923 ├────────────┼─────────┼────────────────────────────────────────────────┤
924 │names │ string │ Comma-separated list of metric names │
925 │times │ boolean │ Append sample times (milliseconds since epoch) │
926 ├────────────┼─────────┼────────────────────────────────────────────────┤
927 │context │ number │ Web context number (optional like hostspec) │
928 │hostspec │ string │ Host specification as described in PCPIntro(1) │
929 │polltimeout │ number │ Seconds of inactivity before context closed │
930 │client │ string │ Request identifier sent back with response │
931 └────────────┴─────────┴────────────────────────────────────────────────┘
932 This request is a subset of the style described in the ``OPEN METRICS''
933 section, allowing a web context identifier to be passed as a parameter.
934 It is otherwise very similar in terms of parameters and response han‐
935 dling, please refer to the earlier section for details.
936
938 For the REST APIs, errors generally result in HTTP-level error respons‐
939 es. Wherever possible, any PMAPI error string will also be provided in
940 a message along with the response.
941 All responses will be returned using HTTP 1.1 protocol and with chunked
943 encoding being used to stream responses that are larger than a config‐
944 ured maximum size. Compression will be used on responses whenever the
945 client indicates appropriate support.
946 An Access-Control-Allow-Origin: * header is added to all REST API re‐
948 sponses.
949
951 PCPIntro(1), curl(1), pmcd(1), pmdaopenmetrics(1), pminfo(1), pmj‐
952 son(1), pmlogger(1), pmproxy(1), pmseries(1), redis-server(1), PCPIn‐
953 tro(3) and PMAPI(3)
954Performance Co-Pilot PCP PMWEBAPI(3)