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 /pmapi/...
13
15 #include <pcp/pmwebapi.h>
16 ... assorted routines ...
18 cc ... -lpcp_web -lpcp
20
22 The PMWEBAPI is a collection of interfaces providing Performance Co-
23 Pilot services for web applications. It consists of APIs for web
24 applications querying and analysing both live and historical perfor‐
25 mance data, as well as APIs used by web servers.
26 The usual HTTP URL-encoded optional parameter rules apply and PMWEBAPI
28 REST requests always follow the convention:
29 /api/endpoint?parameter1=value1¶meter2=value2
31 Examples in all following sections use the curl(1) command line utility
33 with a local pmproxy(1) server listening on port 44322 (default port).
34 The pmjson(1) utility is used to neatly format any JSON output, as
35 opposed to the compact (minimal whitespace) form provided by default.
36 The examples in the scalable time series section use historical data
37 recorded by the pmlogger(1) service, in conjunction with a local redis-
38 server(1).
39
41 Exporting of live performance metrics in an Open Metrics compatible
42 format (as described at https://openmetrics.io and popularized by the
43 https://prometheus.io project) is available.
44 GET /metrics
46 ┌───────────┬─────────┬────────────────────────────────────────────────┐
47 │Parameters │ Type │ Explanation │
48 ├───────────┼─────────┼────────────────────────────────────────────────┤
49 │names │ string │ Comma-separated list of metric names │
50 │times │ boolean │ Append sample times (milliseconds since epoch) │
51 └───────────┴─────────┴────────────────────────────────────────────────┘
52 Fetches current values and metadata for all metrics, or only metrics
53 indicated by a comma-separated list of names.
54 For all numeric metrics with the given NAME prefixes, create an Open
56 Metrics (Prometheus) text export format giving their current value and
57 related metadata.
58 The response has plain text type rather than JSON commonly used else‐
60 where in the REST API. This format can be injested by many open source
61 monitoring tools, including Prometheus and pmdaopenmetrics(1).
62 The native PCP metric metadata (metric name, type, indom, semantics and
64 units) is first output for each metric with # PCP prefix. The metadata
65 reported is of the form described on pmTypeStr(3), pmInDomStr(3),
66 pmSemStr(3) and pmUnitsStr(3) respectively. If the pmUnitsStr(3) units
67 string is empty, then none is output. The units metadata string may
68 contain spaces and extends to the end of the line.
69 PCP metric names are mapped so that the . separators are exchanged with
71 _ (':' in back-compatibility mode, where "# PCP" is the identifying
72 line suffix). Both metric labels and instances are represented as
73 Prometheus labels, with external instance names being quoted and the
74 flattened PCP metric hierarchy being presented with each value.
75 $ curl -s http://localhost:44322/metrics?\
77 names=proc.nprocs,kernel.pernode.cpu.intr,filesys.blocksize
78 # PCP5 proc.nprocs 3.8.99 u32 PM_INDOM_NULL instant none
80 # HELP proc_nprocs instantaneous number of processes
81 # TYPE proc_nprocs gauge
82 proc_nprocs {hostname="app1"} 7
83 # PCP5 kernel.pernode.cpu.intr 60.0.66 u64 60.19 counter millisec
85 # HELP kernel_pernode_cpu_intr total interrupt CPU [...]
86 # TYPE kernel_pernode_cpu_intr counter
87 kernel_pernode_cpu_intr{hostname="app1",instname="node0"} 25603
88 # PCP5 filesys.blocksize 60.5.9 u32 60.5 instant byte
90 # HELP filesys_blocksize Size of each block on mounted file[...]
91 # TYPE filesys_blocksize gauge
92 filesys_blocksize{hostname="app1",instname="/dev/sda1"} 4096
93 filesys_blocksize{hostname="app1",instname="/dev/sda2"} 4096
94
96 The fast, scalable time series query capabilities provided by the pm‐
97 series(1) command are also available through a REST API. These queries
98 provide access to performance data (metric metadata and values) from
99 multiple hosts simultaneously, and in a fashion suited to efficient re‐
100 trieval by any number of web applications.
101 All requests in this group can be accompanied by an optional client pa‐
103 rameter. The value passed in the request will be sent back in the re‐
104 sponse - all responses will be in JSON object form in this case, with
105 top level "client" and "result" fields.
106 GET /series/query - pmSeriesQuery(3)
108 ┌───────────┬────────┬────────────────────────────────────────────┐
109 │Parameters │ Type │ Explanation │
110 ├───────────┼────────┼────────────────────────────────────────────┤
111 │expr │ string │ Query string in pmseries(1) format │
112 │client │ string │ Request identifier sent back with response │
113 └───────────┴────────┴────────────────────────────────────────────┘
114 Performs a time series query for either matching identifiers, or match‐
115 ing identifiers with series of time-stamped values.
116 The query is in the format described in pmseries(1) and is passed to
118 the server via either the expr parameter (HTTP GET) or via the message
119 body (HTTP POST).
120 When querying for time series matches only, no time window options are
122 specified and matching series identifiers are returned in a JSON array.
123 $ curl -s http://localhost:44322/series/query?\
125 expr=disk.dev.read* | pmjson
126 [
127 "9d8c7fb51ce160eb82e3669aac74ba675dfa8900",
128 "ddff1bfe286a3b18cebcbadc1678a68a964fbe9d",
129 "605fc77742cd0317597291329561ac4e50c0dd12"
130 ]
131 When querying for time series values as well, a time window must be
133 specified as part of the query string. The simplest form is to just
134 request the most recent sample.
135 $ curl -s http://localhost:44322/series/query?\
137 expr=disk.dev.read*[samples:1] | pmjson
138 [
139 {
140 "series": "9d8c7fb51ce160eb82e3669aac74ba675dfa8900",
141 "instance": "c3795d8b757506a2901c6b08b489ba56cae7f0d4",
142 "timestamp": 1547483646.2147431,
143 "value": "12499"
144 }, {
145 "series": "ddff1bfe286a3b18cebcbadc1678a68a964fbe9d",
146 "instance": "6b08b489ba56cae7f0d4c3795d8b757506a2901c",
147 "timestamp": 1547485701.7431218,
148 "value": "1118623"
149 }, {
150 "series": "605fc77742cd0317597291329561ac4e50c0dd12",
151 "instance": "c3795d8b757506a2901c6b08b489ba56cae7f0d4",
152 "timestamp": 1547483646.2147431,
153 "value": "71661"
154 }
155 ]
156 GET /series/values - pmSeriesValues(3)
158 ┌───────────┬────────┬────────────────────────────────────────────┐
159 │Parameters │ Type │ Explanation │
160 ├───────────┼────────┼────────────────────────────────────────────┤
161 │series │ string │ Comma-separated list of series identifiers │
162 │client │ string │ Request identifier sent back with response │
163 ├───────────┼────────┼────────────────────────────────────────────┤
164 │samples │ number │ Count of samples to return │
165 │interval │ string │ Time between successive samples │
166 │start │ string │ Sample window start time │
167 │finish │ string │ Sample window end time │
168 │offset │ string │ Sample window offset │
169 │align │ string │ Sample time alignment │
170 │zone │ string │ Time window timezone │
171 └───────────┴────────┴────────────────────────────────────────────┘
172 Performs values retrievals for one or more time series identifiers.
173 The JSON response contains the same information as the pmseries
174 -q/--query option using any of the time window parameters described on
175 pmseries(1). If no time window parameters are specified, the single
176 most recent value observed is retrieved.
177 $ curl -s http://localhost:44322/series/values?\
179 series=605fc77742cd0317597291329561ac4e50c0dd12 | pmjson
180 [
181 {
182 "series": "605fc77742cd0317597291329561ac4e50c0dd12",
183 "timestamp": 1317633022959.959241041,
184 "value": "71660"
185 }
186 ]
187 GET /series/descs - pmSeriesDescs(3)
189 ┌───────────┬────────┬────────────────────────────────────────────┐
190 │Parameters │ Type │ Explanation │
191 ├───────────┼────────┼────────────────────────────────────────────┤
192 │series │ string │ Comma-separated list of series identifiers │
193 │client │ string │ Request identifier sent back with response │
194 └───────────┴────────┴────────────────────────────────────────────┘
195 Performs a descriptor lookup for one or more time series identifiers.
196 The JSON response contains the same information as the pmseries
197 -d/--desc option.
198 $ curl -s http://localhost:44322/series/descs?\
200 series=605fc77742cd0317597291329561ac4e50c0dd12 | pmjson
201 [
202 {
203 "series": "605fc77742cd0317597291329561ac4e50c0dd12",
204 "source": "f5ca7481da8c038325d15612bb1c6473ce1ef16f",
205 "pmid": "60.0.4",
206 "indom": "60.1",
207 "semantics": "counter",
208 "type": "u32",
209 "units": "count",
210 }
211 ]
212 GET /series/labels - pmSeriesLabels(3), pmSeriesLabelValues(3)
214 ┌───────────┬────────┬────────────────────────────────────────────┐
215 │Parameters │ Type │ Explanation │
216 ├───────────┼────────┼────────────────────────────────────────────┤
217 │series │ string │ Comma-separated list of series identifiers │
218 │match │ string │ Glob pattern string to match on all labels │
219 │name │ string │ Find all known label values for given name │
220 │names │ string │ Comma-separated list of label names │
221 │client │ string │ Request identifier sent back with response │
222 └───────────┴────────┴────────────────────────────────────────────┘
223 This command operates in one of three modes. It can perform a label
224 set lookup for one or more time series identifiers, when given the se‐
225 ries parameter). It can produce a list of all known label names, in
226 the absense of name, names or series parameters. The JSON responses
227 for these modes contains the same information as the pmseries -l/--la‐
228 bels option.
229 Alternatively, it can produce a list of all known label values for a
231 given label name or names. The JSON response for this mode contains
232 the same information as the pmseries -v/--values option.
233 $ curl -s http://localhost:44322/series/labels?\
235 series=605fc77742cd0317597291329561ac4e50c0dd12 | pmjson
236 [
237 {
238 "series": "605fc77742cd0317597291329561ac4e50c0dd12",
239 "labels": {
240 "agent": "linux",
241 "domainname": "acme.com",
242 "groupid": 1000,
243 "hostname": "www.acme.com",
244 "latitude": -25.28496,
245 "longitude": 152.87886,
246 "machineid": "295b16e3b6074cc8bdbda8bf96f6930a",
247 "platform": "dev",
248 "userid": 1000
249 }
250 }
251 ]
252 Alternatively, with no name, names or series parameters, return the
254 list of all known label names.
255 $ curl -s http://localhost:44322/series/labels | pmjson
257 [
258 "agent",
259 "appversion",
260 "domainname",
261 "groupid",
262 "hostname",
263 "jobid",
264 "latitude",
265 "longitude",
266 "machineid",
267 "platform",
268 "userid"
269 ]
270 Use the name or names parameters to find all possible label values for
272 the given name(s).
273 $ curl -s http://localhost:44322/series/labels?\
275 names=hostname,domainname | pmjson
276 {
277 "hostname": [ "app", "nas" ],
278 "domainname": [ "acme.com" ]
279 }
280 GET /series/metrics - pmSeriesMetrics(3)
282 ┌───────────┬────────┬────────────────────────────────────────────┐
283 │Parameters │ Type │ Explanation │
284 ├───────────┼────────┼────────────────────────────────────────────┤
285 │series │ string │ Comma-separated list of series identifiers │
286 │match │ string │ Glob pattern string to match on all names │
287 │client │ string │ Request identifier sent back with response │
288 └───────────┴────────┴────────────────────────────────────────────┘
289 Performs a metric name lookup for one or more time series identifiers.
290 The JSON response contains the same information as the pmseries
291 -m/--metrics option.
292 $ curl -s http://localhost:44322/series/metrics?\
294 series=605fc77742cd0317597291329561ac4e50c0dd12 | pmjson
295 [
296 {
297 "series": "605fc77742cd0317597291329561ac4e50c0dd12",
298 "name": "disk.dev.read_bytes"
299 }
300 ]
301 Alternatively, with no series argument, this request will return the
303 list of all known metric names.
304 $ curl -s http://localhost:44322/series/metrics | pmjson
306 [
307 "disk.dev.read",
308 "disk.dev.read_bytes",
309 "disk.dev.read_merge",
310 "kernel.all.load",
311 "kernel.all.pswitch",
312 ...
313 ]
314 GET /series/sources - pmSeriesSources(3)
316 ┌───────────┬────────┬─────────────────────────────────────────────┐
317 │Parameters │ Type │ Explanation │
318 ├───────────┼────────┼─────────────────────────────────────────────┤
319 │series │ string │ Comma-separated list of source identifiers │
320 │match │ string │ Glob pattern string to match on all sources │
321 │client │ string │ Request identifier sent back with response │
322 └───────────┴────────┴─────────────────────────────────────────────┘
323 Performs a lookup for one or more time series sources, returning an ar‐
324 ray of all PMAPI context names used to access the time series from that
325 source. The JSON response contains the same information as the pm‐
326 series -S/--source option.
327 $ curl -s http://localhost:44322/series/sources?\
329 source=2cd6a38f9339f2dd1f0b4775bda89a9e7244def6 | pmjson
330 [
331 {
332 "source": "2cd6a38f9339f2dd1f0b4775bda89a9e7244def6",
333 "context": [
334 "/var/log/pcp/pmlogger/acme",
335 "www.acme.com"
336 ]
337 }
338 ]
339 GET /series/instances - pmSeriesInstances(3)
341 ┌───────────┬────────┬───────────────────────────────────────────────┐
342 │Parameters │ Type │ Explanation │
343 ├───────────┼────────┼───────────────────────────────────────────────┤
344 │series │ string │ Comma-separated list of series identifiers │
345 │match │ string │ Glob pattern string to match on all instances │
346 │client │ string │ Request identifier sent back with response │
347 └───────────┴────────┴───────────────────────────────────────────────┘
348 Provide instance identifiers and names for one or more time series
349 identifiers. The JSON response contains the same information as the
350 pmseries -i/--instance option.
351 $ curl -s http://localhost:44322/series/instances?\
353 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&\
401 expr={source.name:"/var/log/pcp/pmlogger/acme"}
402 {
403 "success": true
404 }
405
407 The live performance collection facilities available from pmcd(1) can
408 also be accessed through a REST API.
409 All requests are performed on the web server host by default, unless
411 either a hostspec or context parameter is provided. hostname can be
412 used in place of hostspec.
413 Context identifiers are used as a persistent way to refer to PMAPI con‐
415 texts across related web requests. These contexts expire after a con‐
416 figurable period of disuse, and are explicitly allocated using the
417 /pmapi/context interface.
418 The timeout interval is configurable at context creation time, and as
420 such the polltime parameter can be used anywhere the hostspec is speci‐
421 fied. It sets the context timeout in terms of length of inactive time.
422 The unit for the timeout value is seconds.
423 To specify a specific existing context in any PMAPI web request, the
425 endpoints can be accessed with either the context parameter or enbedded
426 in the endpoint URL itself, such as /pmapi/[number]/fetch.
427 GET /pmapi/context - pmNewContext(3)
429 ┌────────────┬────────┬────────────────────────────────────────────────┐
430 │Parameters │ Type │ Explanation │
431 ├────────────┼────────┼────────────────────────────────────────────────┤
432 │hostspec │ string │ Host specification as described in PCPIntro(1) │
433 │polltimeout │ number │ Seconds of inactivity before closing context │
434 │client │ string │ Request identifier sent back with response │
435 └────────────┴────────┴────────────────────────────────────────────────┘
436 To create a context for live sampling, a web client can access any
437 /pmapi URL (optionally using the hostspec or context parameter). If no
438 context exists, a new one will be created for that web client, and its
439 identifier returned for future accesses.
440 However, /pmapi/context is provided as a dedicated URL for applications
442 wishing to explicitly create the contexts they use.
443 If successful, the server responds with a HTTP 200 (OK) code and JSON
445 message body of the form:
446 $ curl -s http://localhost:44322/pmapi/context?\
448 hostspec=www.acme.com&polltime=500 | pmjson
449 {
450 "context": 348734,
451 "source": "05af7f3eb840277fd3cfa91f90ef0067199743c",
452 "hostspec": "www.acme.com",
453 "labels": {
454 "domainname": "acme.com",
455 "groupid": 1000,
456 "hostname": "www.acme.com",
457 "machineid": "295b7623b6074cc8bdbda8bf96f6930a"
458 "platform": "dev",
459 "userid": 1000
460 }
461 }
462 The context (a 32-bit unsigned decimal number) can then be used with
464 all later requests.
465 In the case of a hostspec containing authentication information, such
467 as a username, the server will follow the HTTP Basic Authentication
468 protocol to ascertain necessary authentication details from the user,
469 providing the client web application an opportunity to request these
470 from the user.
471 GET /pmapi/metric - pmLookupDesc(3), pmLookupLabels(3), pmLookupName(3),
473 pmLookupText(3)
474 ┌────────────┬────────┬────────────────────────────────────────────────┐
475 │Parameters │ Type │ Explanation │
476 ├────────────┼────────┼────────────────────────────────────────────────┤
477 │name │ string │ An individual metric name │
478 │names │ string │ Comma-separated list of metric names │
479 │pmid │ pmID │ Numeric or pmIDStr(3) metric identifier │
480 │pmids │ string │ Comma-separated numeric or pmIDStr(3) pmIDs │
481 │prefix │ string │ Metric namespace component as in PMNS(5) │
482 ├────────────┼────────┼────────────────────────────────────────────────┤
483 │hostspec │ string │ Host specification as described in PCPIntro(1) │
484 │context │ number │ Web context number (optional like hostspec) │
485 │polltimeout │ number │ Seconds of inactivity before context closed │
486 │client │ string │ Request identifier sent back with response │
487 └────────────┴────────┴────────────────────────────────────────────────┘
488 The metric endpoint provides detailed PMAPI metric metadata for one or
489 more metrics. If no parameters are supplied, the response will be for
490 all metrics found when traversing the entire Performance Metrics Name
491 Space (PMNS).
492 The prefix parameter can be used to specify a subtree of the PMNS for
494 traversal. Alternatively, a specific metric or comma-separated list of
495 metrics can be specified using either name or names
496 The server response is a JSON document that provides metric metadata as
498 an array.
499 $ curl -s http://localhost:44322/pmapi/metric?\
501 names=kernel.all.load,disk.all.read | pmjson
502 {
503 "context": 348734,
504 "metrics": [
505 {
506 "name": "kernel.all.load",
507 "pmid": "60.2.0",
508 "indom": "60.2",
509 "type": "FLOAT",
510 "sem": "instant",
511 "units": "none",
512 "series": "d2b28c7f6dc0d69ffd21dba7ba955e78c37719b",
513 "source": "05af7f3eb840277fd3cfa91f90ef0067199743c",
514 "labels": {
515 "agent": "linux",
516 "domainname": "acme.com",
517 "groupid": 1000,
518 "hostname": "www.acme.com",
519 "platform": "dev",
520 "userid": 1000
521 },
522 "text-oneline": "1, 5 and 15 minute load average"
523 },
524 {
525 "name": "disk.all.read",
526 "pmid": "60.0.24",
527 "type": "U64",
528 "sem": "counter",
529 "units": "count",
530 "series": "d2b28c7f6dc0d69ffd21dba7ba955e78c37719b",
531 "source": "05af7f3eb840277fd3cfa91f90ef0067199743c",
532 "labels": {
533 "agent": "linux",
534 "domainname": "acme.com",
535 "groupid": 1000,
536 "hostname": "www.acme.com",
537 "platform": "dev",
538 "userid": 1000
539 },
540 "text-oneline": "total read operations, summed for all disks",
541 "text-help": "Cumulative number of disk read operations [...]"
542 }
543 ]
544 }
545 Most of the fields are directly transcribed from the PMAPI calls for
546 metric descriptors, labels and help text mentioned above and are exact‐
547 ly as would be observed using the pminfo(1) command with the -dlmstT
548 options.
549 The semantics, type and units fields are as returned by pmTypeStr(3),
551 pmUnitsStr(3) and pmSemStr(3).
552 GET /pmapi/fetch - pmFetch(3)
554 ┌────────────┬────────┬────────────────────────────────────────────────┐
555 │Parameters │ Type │ Explanation │
556 ├────────────┼────────┼────────────────────────────────────────────────┤
557 │delta │ string │ Sampling interval in pmParseInterval(3) form │
558 │name │ string │ An individual metric name │
559 │names │ string │ Comma-separated list of metric names │
560 │pmid │ pmID │ Numeric or pmIDStr(3) metric identifier │
561 │pmids │ string │ Comma-separated numeric or pmIDStr(3) pmIDs │
562 ├────────────┼────────┼────────────────────────────────────────────────┤
563 │hostspec │ string │ Host specification as described in PCPIntro(1) │
564 │context │ number │ Web context number (optional like hostspec) │
565 │polltimeout │ number │ Seconds of inactivity before context closed │
566 │client │ string │ Request identifier sent back with response │
567 └────────────┴────────┴────────────────────────────────────────────────┘
568 This request fetches (samples) current values for given metrics.
569 If any of the names or pmids provided are valid, the response is a JSON
571 document that provides the values for all instances of the metrics, un‐
572 less a instance profile has been set for the web context (see section
573 on InDom profiles below).
574 $ curl -s http://localhost:44322/pmapi/fetch?\
576 names=kernel.all.load,disk.all.read | pmjson
577 {
578 "context": 348734,
579 "timestamp": 1547483646.2147431,
580 "values": [
581 {
582 "pmid": "60.2.0",
583 "name": "kernel.all.load",
584 "instances:" [
585 { "instance": 1, "value": 0.1 },
586 { "instance": 5, "value": 0.17 },
587 { "instance": 15, "value": 0.22 }
588 ]
589 },
590 {
591 "pmid":"60.0.24",
592 "name":"disk.all.read",
593 "instances:" [
594 { "instance": null, "value": 639231 }
595 ]
596 }
597 ]
598 }
599 The response fields map directly to fields from the underlying pm‐
600 Fetch(3) sampling interface.
601 Numeric metric types are represented as JSON integer or floating-point
603 values. Strings are passed verbatim, except that non-ASCII values are
604 replaced with a Unicode 0xFFFD replacement character code.
605 In backward compatibility mode the timestamp is presented as a JSON map
607 with second (sec) and microsecond (us) fields, instead of using the
608 more compact floating point representation shown above.
609 GET /pmapi/children - pmGetChildren(3), pmGetChildrenStatus(3)
611 ┌────────────┬────────┬────────────────────────────────────────────────┐
612 │Parameters │ Type │ Explanation │
613 ├────────────┼────────┼────────────────────────────────────────────────┤
614 │prefix │ string │ Metric namespace component as in PMNS(5) │
615 ├────────────┼────────┼────────────────────────────────────────────────┤
616 │hostspec │ string │ Host specification as described in PCPIntro(1) │
617 │context │ number │ Web context number (optional like hostspec) │
618 │polltimeout │ number │ Seconds of inactivity before context closed │
619 │client │ string │ Request identifier sent back with response │
620 └────────────┴────────┴────────────────────────────────────────────────┘
621 The children endpoint provides iterative namespace traversal for a con‐
622 text. If no parameters are supplied, the response will describe the
623 direct descendants of the Performance Metrics Name Space (PMNS) root.
624 The prefix parameter can be used to specify a subtree of the PMNS for
626 traversal.
627 The server response is a JSON document that provides the set of leaf
629 and non-leaf nodes below the given namespace node or root.
630 $ curl -s http://localhost:44322/pmapi/children?prefix=mem | pmjson
632 {
633 "context": 348734,
634 "name": "mem",
635 "leaf": [
636 "physmem",
637 "freemem"
638 ],
639 "nonleaf": [
640 "util",
641 "numa",
642 "vmstat",
643 "buddyinfo",
644 "slabinfo",
645 "zoneinfo",
646 "ksm"
647 ]
648 }
649 GET /pmapi/indom - pmGetInDom(3), pmNameInDom(3), pmLookupInDom(3)
651 ┌────────────┬─────────┬────────────────────────────────────────────────┐
652 │Parameters │ Type │ Explanation │
653 ├────────────┼─────────┼────────────────────────────────────────────────┤
654 │iname │ string │ Comma-separated list of instance names │
655 │indom │ pmInDom │ Numeric or pmInDomStr(3) instance domain │
656 │instance │ number │ Comma-separated list of instance numbers │
657 │match │ string │ Pattern matching style (exact, glob or regex) │
658 │name │ string │ An individual metric name │
659 ├────────────┼─────────┼────────────────────────────────────────────────┤
660 │hostspec │ string │ Host specification as described in PCPIntro(1) │
661 │context │ number │ Web context number (optional like hostspec) │
662 │polltimeout │ number │ Seconds of inactivity before context closed │
663 │client │ string │ Request identifier sent back with response │
664 └────────────┴─────────┴────────────────────────────────────────────────┘
665 This request lists the current instances of an instance domain. The
666 instance domain is either specified directly (in numeric or string
667 form) or indirectly, by association with the specified metric.
668 The request can be further qualified with a comma-separated list of the
670 instances to report on, either by name or number, using the instance
671 and iname parameters.
672 In the case of instance name qualifiers, these will be matched by exact
674 string comparison by default. Alternatively, the match parameter can
675 be used to specify that regular expression or glob pattern matching
676 should be used instead.
677 The response is a JSON document that provides the instance domain meta‐
679 data as an array.
680 $ curl -s http://localhost:44322/pmapi/indom?\
682 name=kernel.all.load | pmjson
683 {
684 "context": 348734,
685 "indom": "60.2",
686 "labels": {
687 "domainname": "acme.com",
688 "groupid": 1000,
689 "hostname": "www.acme.com",
690 "machineid": "295b7623b6074cc8bdbda8bf96f6930a"
691 "platform": "dev",
692 "userid": 1000
693 },
694 "instances": [
695 {
696 "instance": 1,
697 "name": "1 minute"
698 "labels": { ... },
699 },
700 {
701 "instance": 5,
702 "name": "5 minute"
703 "labels": { ... },
704 },
705 {
706 "instance": 15,
707 "name": "15 minute"
708 "labels": { ... },
709 }
710 ]
711 }
712 GET /pmapi/profile - pmAddProfile(3), pmDelProfile(3)
714 ┌────────────┬─────────┬────────────────────────────────────────────────┐
715 │Parameters │ Type │ Explanation │
716 ├────────────┼─────────┼────────────────────────────────────────────────┤
717 │iname │ string │ Comma-separated list of instance names │
718 │indom │ pmInDom │ Numeric or pmInDomStr(3) instance domain │
719 │instance │ number │ Comma-separated list of instance numbers │
720 │expr │ string │ One of "add" or "del" (mandatory). │
721 │match │ string │ Pattern matching style (exact, glob or regex) │
722 ├────────────┼─────────┼────────────────────────────────────────────────┤
723 │hostspec │ string │ Host specification as described in PCPIntro(1) │
724 │context │ number │ Web context number (optional like hostspec) │
725 │polltimeout │ number │ Seconds of inactivity before context closed │
726 │client │ string │ Request identifier sent back with response │
727 └────────────┴─────────┴────────────────────────────────────────────────┘
728 Some PMAPI operations can be performed with an active instance domain
729 profile which restricts (filters) the set of resulting instances re‐
730 turned, as described on pmAddProfile(3).
731 $ curl -s http://localhost:44322/pmapi/profile?\
733 expr=add,indom=60.2,iname=1%20minute
734 { "context": 348734, "success": true }
735 GET /pmapi/store - pmStore(3)
737 ┌────────────┬────────┬────────────────────────────────────────────────┐
738 │Parameters │ Type │ Explanation │
739 ├────────────┼────────┼────────────────────────────────────────────────┤
740 │iname │ string │ Comma-separated list of instance names │
741 │instance │ number │ Comma-separated list of instance numbers │
742 │name │ string │ An individual metric name │
743 │value │ (any) │ New value for the given metric instance(s) │
744 ├────────────┼────────┼────────────────────────────────────────────────┤
745 │hostspec │ string │ Host specification as described in PCPIntro(1) │
746 │context │ number │ Web context number optional like hostspec) │
747 │polltimeout │ number │ Seconds of inactivity before context closed │
748 └────────────┴────────┴────────────────────────────────────────────────┘
749 Some performance metrics allow their value to be modified, for example
750 to re-initialize counters or to modify control variables.
751 This operation takes a single metric name to modify, and optionally
753 specific instances. The mandatory value will be interpreted according
754 to the type of the metric being modified.
755 If successful, the response from these requests is a JSON document of
757 the form:
758 $ curl -s http://localhost:44322/pmapi/store?\
760 name=pmcd.control.timeout&value=10
761 {
762 "context": 348734,
763 "success": true
764 }
765 GET /pmapi/derive: pmRegisterDerived(3)
767 ┌───────────┬────────┬────────────────────────────────────────────┐
768 │Parameters │ Type │ Explanation │
769 ├───────────┼────────┼────────────────────────────────────────────┤
770 │expr │ string │ Derived metric expression │
771 │name │ string │ New derived metric name │
772 ├───────────┼────────┼────────────────────────────────────────────┤
773 │client │ string │ Request identifier sent back with response │
774 └───────────┴────────┴────────────────────────────────────────────┘
775 Create a new derived metric, as defined by the pmRegisterDerived(3)
776 metric interface. Derived metrics are not associated with any particu‐
777 lar context and must be registered before creation (or reconnect) of
778 any context wishing to use the new metric.
779 This interface is one of the few that allows a POST to be used in place
781 of a GET. In this case the HTTP POST request body may be used to pro‐
782 vide one or more derived metrics specification (all at once, across
783 multiple lines, as a convenience).
784 $ curl -s http://localhost:44322/pmapi/derive?\
786 name=blkio.avgsz&expr=disk.all.blktotal/disk.all.total | pmjson
787 {
788 "success": true
789 }
790 $ curl -s http://localhost:44322/pmapi/fetch?\
792 name=blkio.avgsz&samples=2 | pmjson
793 {
794 "context": 348734,
795 "timestamp": 1547483648.2147428,
796 "values": [
797 {
798 "pmid": "511.0.27",
799 "name": "blkio.avgsz",
800 "instances:" [
801 {
802 "instance": null,
803 "value": 9231
804 }
805 ]
806 }
807 ]
808 }
809 GET /pmapi/metrics: pmLookupDesc(3),pmLookupLabels(3), pmFetch(3)
811 ┌────────────┬─────────┬────────────────────────────────────────────────┐
812 │Parameters │ Type │ Explanation │
813 ├────────────┼─────────┼────────────────────────────────────────────────┤
814 │names │ string │ Comma-separated list of metric names │
815 │times │ boolean │ Append sample times (milliseconds since epoch) │
816 ├────────────┼─────────┼────────────────────────────────────────────────┤
817 │context │ number │ Web context number (optional like hostspec) │
818 │hostspec │ string │ Host specification as described in PCPIntro(1) │
819 │polltimeout │ number │ Seconds of inactivity before context closed │
820 │client │ string │ Request identifier sent back with response │
821 └────────────┴─────────┴────────────────────────────────────────────────┘
822 This request is a subset of the style described in the ``OPEN METRICS''
823 section, allowing a web context identifier to be passed as a parameter.
824 It is otherwise very similar in terms of parameters and response han‐
825 dling, please refer to the earlier section for details.
826
828 For the REST APIs, errors generally result in HTTP-level error respons‐
829 es. Wherever possible, any PMAPI error string will also be provided in
830 a message along with the response.
831 All responses will be returned using HTTP 1.1 protocol and with chunked
833 encoding being used to stream responses that are larger than a config‐
834 ured maximum size. Compression will be used on responses whenever the
835 client indicates appropriate support.
836 An Access-Control-Allow-Origin: * header is added to all REST API re‐
838 sponses.
839
841 PCPIntro(1), curl(1), pmcd(1), pmdaopenmetrics(1), pminfo(1), pmj‐
842 son(1), pmlogger(1), pmproxy(1), pmseries(1), redis-server(1), PCPIn‐
843 tro(3) and PMAPI(3)
844Performance Co-Pilot PCP PMWEBAPI(3)