1PMWEBAPI(3)                Library Functions Manual                PMWEBAPI(3)
2
3
4

NAME

6       PMWEBAPI - introduction to the Performance Metrics Web Application Pro‐
7       gramming Interface
8

HTTP SYNOPSIS

10       GET /metrics
11       GET /series/...
12       GET /pmapi/...
13

C SYNOPSIS

15       #include <pcp/pmwebapi.h>
16
17        ... assorted routines ...
18
19       cc ... -lpcp_web -lpcp
20

DESCRIPTION

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
27       The  usual HTTP URL-encoded optional parameter rules apply and PMWEBAPI
28       REST requests always follow the convention:
29
30       /api/endpoint?parameter1=value1&parameter2=value2
31
32       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

OPEN METRICS

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
45   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
55       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
59       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
63       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
70       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
76         $ curl -s http://localhost:44322/metrics?\
77                    names=proc.nprocs,kernel.pernode.cpu.intr,filesys.blocksize
78
79         # 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
84         # 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
89         # 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

SCALABLE TIME SERIES

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
102       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
107   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
117       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
121       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
124         $ curl -s http://localhost:44322/series/query?\
125                    expr=disk.dev.read* | pmjson
126         [
127           "9d8c7fb51ce160eb82e3669aac74ba675dfa8900",
128           "ddff1bfe286a3b18cebcbadc1678a68a964fbe9d",
129           "605fc77742cd0317597291329561ac4e50c0dd12"
130         ]
131
132       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
136         $ 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
157   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
178         $ 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
188   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
199         $ 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
213   GET /series/labels - pmSeriesLabels(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       │client     │ string │ Request identifier sent back with response │
220       └───────────┴────────┴────────────────────────────────────────────┘
221       Performs  a  label  set lookup for one or more time series identifiers.
222       The JSON  response  contains  the  same  information  as  the  pmseries
223       -l/--labels option.
224
225         $ curl -s http://localhost:44322/series/labels?\
226                    series=605fc77742cd0317597291329561ac4e50c0dd12 | pmjson
227         [
228           {
229             "series": "605fc77742cd0317597291329561ac4e50c0dd12",
230             "labels": {
231               "agent": "linux",
232               "domainname": "acme.com",
233               "groupid": 1000,
234               "hostname": "www.acme.com",
235               "latitude": -25.28496,
236               "longitude": 152.87886,
237               "machineid": "295b16e3b6074cc8bdbda8bf96f6930a",
238               "platform": "dev",
239               "userid": 1000
240             }
241           }
242         ]
243
244       Alternatively,  with  no  series argument, this request will return the
245       list of all known label names.
246
247         $ curl -s http://localhost:44322/series/labels | pmjson
248         [
249             "agent",
250             "appversion",
251             "domainname",
252             "groupid",
253             "hostname",
254             "jobid",
255             "latitude",
256             "longitude",
257             "machineid",
258             "platform",
259             "userid"
260         ]
261
262   GET /series/metrics - pmSeriesMetrics(3)
263       ┌───────────┬────────┬────────────────────────────────────────────┐
264       │Parameters │  Type  │                Explanation                 │
265       ├───────────┼────────┼────────────────────────────────────────────┤
266       │series     │ string │ Comma-separated list of series identifiers │
267       │match      │ string │ Glob pattern string to match on all names  │
268       │client     │ string │ Request identifier sent back with response │
269       └───────────┴────────┴────────────────────────────────────────────┘
270       Performs a metric name lookup for one or more time series  identifiers.
271       The  JSON  response  contains  the  same  information  as  the pmseries
272       -m/--metrics option.
273
274         $ curl -s http://localhost:44322/series/metrics?\
275                    series=605fc77742cd0317597291329561ac4e50c0dd12 | pmjson
276         [
277           {
278             "series": "605fc77742cd0317597291329561ac4e50c0dd12",
279             "name": "disk.dev.read_bytes"
280           }
281         ]
282
283       Alternatively, with no series argument, this request  will  return  the
284       list of all known metric names.
285
286         $ curl -s http://localhost:44322/series/metrics | pmjson
287         [
288             "disk.dev.read",
289             "disk.dev.read_bytes",
290             "disk.dev.read_merge",
291             "kernel.all.load",
292             "kernel.all.pswitch",
293             ...
294         ]
295
296   GET /series/sources - pmSeriesSources(3)
297       ┌───────────┬────────┬─────────────────────────────────────────────┐
298       │Parameters │  Type  │                 Explanation                 │
299       ├───────────┼────────┼─────────────────────────────────────────────┤
300       │series     │ string │ Comma-separated list of source identifiers  │
301       │match      │ string │ Glob pattern string to match on all sources │
302       │client     │ string │ Request identifier sent back with response  │
303       └───────────┴────────┴─────────────────────────────────────────────┘
304       Performs a lookup for one or more time series sources, returning an ar‐
305       ray of all PMAPI context names used to access the time series from that
306       source.   The  JSON  response  contains the same information as the pm‐
307       series -S/--source option.
308
309         $ curl -s http://localhost:44322/series/sources?\
310                    source=2cd6a38f9339f2dd1f0b4775bda89a9e7244def6 | pmjson
311         [
312           {
313             "source": "2cd6a38f9339f2dd1f0b4775bda89a9e7244def6",
314             "context": [
315               "/var/log/pcp/pmlogger/acme",
316               "www.acme.com"
317             ]
318           }
319         ]
320
321   GET /series/instances - pmSeriesInstances(3)
322       ┌───────────┬────────┬───────────────────────────────────────────────┐
323       │Parameters │  Type  │                  Explanation                  │
324       ├───────────┼────────┼───────────────────────────────────────────────┤
325       │series     │ string │ Comma-separated list of series identifiers    │
326       │match      │ string │ Glob pattern string to match on all instances │
327       │client     │ string │ Request identifier sent back with response    │
328       └───────────┴────────┴───────────────────────────────────────────────┘
329       Provide instance identifiers and names for  one  or  more  time  series
330       identifiers.   The  JSON  response contains the same information as the
331       pmseries -i/--instance option.
332
333         $ curl -s http://localhost:44322/series/instances?\
334                    series=605fc77742cd0317597291329561ac4e50c0dd12 | pmjson
335         [
336           {
337             "series": "605fc77742cd0317597291329561ac4e50c0dd12",
338             "source": "97261ac7742cd4e50c0d03175913295d12605fc7",
339             "instance": "c3795d8b757506a2901c6b08b489ba56cae7f0d4"
340             "id": 1,
341             "name": "sda",
342           }, {
343             "series": "605fc77742cd0317597291329561ac4e50c0dd12",
344             "source": "97261ac7742cd4e50c0d03175913295d12605fc7",
345             "instance": "57506a2901c6b08b489ba56cae7f0d4c3795d8b7"
346             "id": 2,
347             "name": "sdb",
348           }
349         ]
350
351       Alternatively, with no series argument, this request  will  return  the
352       list of all known instance names.
353
354         $ curl -s http://localhost:44322/series/instances | pmjson
355         [
356             "1 minute",
357             "5 minute",
358             "15 minute",
359             "cpu0",
360             "cpu1",
361             "cpu2",
362             "cpu3",
363             "node0",
364             "node1",
365             "sda",
366             "sdb",
367             ...
368         ]
369
370   GET /series/load - pmSeriesLoad(3)
371       ┌───────────┬────────┬────────────────────────────────────────────┐
372       │Parameters │  Type  │                Explanation                 │
373       ├───────────┼────────┼────────────────────────────────────────────┤
374       │expr       │ string │ Source load string in pmseries(1) format   │
375       │client     │ string │ Request identifier sent back with response │
376       └───────────┴────────┴────────────────────────────────────────────┘
377       Load  time  series  performance data from the specified source into the
378       redis-server  cache.   This  request  is  equivalent  to  the  pmseries
379       -l/--load option.
380
381         $ curl -s http://localhost:44322/series/load&\
382                    expr={source.name:"/var/log/pcp/pmlogger/acme"}
383         {
384           "success": true
385         }
386

PMAPI HOST SERVICES

388       The  live  performance collection facilities available from pmcd(1) can
389       also be accessed through a REST API.
390
391       All requests are performed on the web server host  by  default,  unless
392       either  a  hostspec  or context parameter is provided.  hostname can be
393       used in place of hostspec.
394
395       Context identifiers are used as a persistent way to refer to PMAPI con‐
396       texts  across related web requests.  These contexts expire after a con‐
397       figurable period of disuse, and  are  explicitly  allocated  using  the
398       /pmapi/context interface.
399
400       The  timeout  interval is configurable at context creation time, and as
401       such the polltime parameter can be used anywhere the hostspec is speci‐
402       fied.  It sets the context timeout in terms of length of inactive time.
403       The unit for the timeout value is seconds.
404
405       To specify a specific existing context in any PMAPI  web  request,  the
406       endpoints can be accessed with either the context parameter or enbedded
407       in the endpoint URL itself, such as /pmapi/[number]/fetch.
408
409   GET /pmapi/context - pmNewContext(3)
410       ┌────────────┬────────┬────────────────────────────────────────────────┐
411       │Parameters  │  Type  │                  Explanation                   │
412       ├────────────┼────────┼────────────────────────────────────────────────┤
413       │hostspec    │ string │ Host specification as described in PCPIntro(1)
414       │polltimeout │ number │ Seconds of inactivity before closing context   │
415       │client      │ string │ Request identifier sent back with response     │
416       └────────────┴────────┴────────────────────────────────────────────────┘
417       To create a context for live sampling, a  web  client  can  access  any
418       /pmapi URL (optionally using the hostspec or context parameter).  If no
419       context exists, a new one will be created for that web client, and  its
420       identifier returned for future accesses.
421
422       However, /pmapi/context is provided as a dedicated URL for applications
423       wishing to explicitly create the contexts they use.
424
425       If successful, the server responds with a HTTP 200 (OK) code  and  JSON
426       message body of the form:
427
428         $ curl -s http://localhost:44322/pmapi/context?\
429                     hostspec=www.acme.com&polltime=500 | pmjson
430         {
431           "context": 348734,
432           "source": "05af7f3eb840277fd3cfa91f90ef0067199743c",
433           "hostspec": "www.acme.com",
434           "labels": {
435             "domainname": "acme.com",
436             "groupid": 1000,
437             "hostname": "www.acme.com",
438             "machineid": "295b7623b6074cc8bdbda8bf96f6930a"
439             "platform": "dev",
440             "userid": 1000
441           }
442         }
443
444       The  context  (a  32-bit unsigned decimal number) can then be used with
445       all later requests.
446
447       In the case of a hostspec containing authentication  information,  such
448       as  a  username,  the  server will follow the HTTP Basic Authentication
449       protocol to ascertain necessary authentication details from  the  user,
450       providing  the  client  web application an opportunity to request these
451       from the user.
452
453   GET /pmapi/metric -  pmLookupDesc(3),  pmLookupLabels(3),  pmLookupName(3),
454       pmLookupText(3)
455       ┌────────────┬────────┬────────────────────────────────────────────────┐
456       │Parameters  │  Type  │                  Explanation                   │
457       ├────────────┼────────┼────────────────────────────────────────────────┤
458       │name        │ string │ An individual metric name                      │
459       │names       │ string │ Comma-separated list of metric names           │
460       │pmid        │ pmID   │ Numeric or pmIDStr(3) metric identifier        │
461       │pmids       │ string │ Comma-separated numeric or pmIDStr(3) pmIDs    │
462       │prefix      │ string │ Metric namespace component as in PMNS(5)
463       ├────────────┼────────┼────────────────────────────────────────────────┤
464       │hostspec    │ string │ Host specification as described in PCPIntro(1)
465       │context     │ number │ Web context number (optional like hostspec)    │
466       │polltimeout │ number │ Seconds of inactivity before context closed    │
467       │client      │ string │ Request identifier sent back with response     │
468       └────────────┴────────┴────────────────────────────────────────────────┘
469       The  metric endpoint provides detailed PMAPI metric metadata for one or
470       more metrics.  If no parameters are supplied, the response will be  for
471       all  metrics  found when traversing the entire Performance Metrics Name
472       Space (PMNS).
473
474       The prefix parameter can be used to specify a subtree of the  PMNS  for
475       traversal.  Alternatively, a specific metric or comma-separated list of
476       metrics can be specified using either name or names
477
478       The server response is a JSON document that provides metric metadata as
479       an array.
480
481         $ curl -s http://localhost:44322/pmapi/metric?\
482                     names=kernel.all.load,disk.all.read | pmjson
483         {
484           "context": 348734,
485           "metrics": [
486             {
487               "name": "kernel.all.load",
488               "pmid": "60.2.0",
489               "indom": "60.2",
490               "type": "FLOAT",
491               "sem": "instant",
492               "units": "none",
493               "series": "d2b28c7f6dc0d69ffd21dba7ba955e78c37719b",
494               "source": "05af7f3eb840277fd3cfa91f90ef0067199743c",
495               "labels": {
496                 "agent": "linux",
497                 "domainname": "acme.com",
498                 "groupid": 1000,
499                 "hostname": "www.acme.com",
500                 "platform": "dev",
501                 "userid": 1000
502               },
503               "text-oneline": "1, 5 and 15 minute load average"
504             },
505             {
506               "name": "disk.all.read",
507               "pmid": "60.0.24",
508               "type": "U64",
509               "sem": "counter",
510               "units": "count",
511               "series": "d2b28c7f6dc0d69ffd21dba7ba955e78c37719b",
512               "source": "05af7f3eb840277fd3cfa91f90ef0067199743c",
513               "labels": {
514                 "agent": "linux",
515                 "domainname": "acme.com",
516                 "groupid": 1000,
517                 "hostname": "www.acme.com",
518                 "platform": "dev",
519                 "userid": 1000
520               },
521               "text-oneline": "total read operations, summed for all disks",
522               "text-help": "Cumulative number of disk read operations [...]"
523             }
524           ]
525         }
526       Most  of  the  fields are directly transcribed from the PMAPI calls for
527       metric descriptors, labels and help text mentioned above and are exact‐
528       ly  as  would  be observed using the pminfo(1) command with the -dlmstT
529       options.
530
531       The semantics, type and units fields are as returned  by  pmTypeStr(3),
532       pmUnitsStr(3) and pmSemStr(3).
533
534   GET /pmapi/fetch - pmFetch(3)
535       ┌────────────┬────────┬────────────────────────────────────────────────┐
536       │Parameters  │  Type  │                  Explanation                   │
537       ├────────────┼────────┼────────────────────────────────────────────────┤
538       │delta       │ string │ Sampling interval in pmParseInterval(3) form   │
539       │name        │ string │ An individual metric name                      │
540       │names       │ string │ Comma-separated list of metric names           │
541       │pmid        │ pmID   │ Numeric or pmIDStr(3) metric identifier        │
542       │pmids       │ string │ Comma-separated numeric or pmIDStr(3) pmIDs    │
543       ├────────────┼────────┼────────────────────────────────────────────────┤
544       │hostspec    │ string │ Host specification as described in PCPIntro(1)
545       │context     │ number │ Web context number (optional like hostspec)    │
546       │polltimeout │ number │ Seconds of inactivity before context closed    │
547       │client      │ string │ Request identifier sent back with response     │
548       └────────────┴────────┴────────────────────────────────────────────────┘
549       This request fetches (samples) current values for given metrics.
550
551       If any of the names or pmids provided are valid, the response is a JSON
552       document that provides the values for all instances of the metrics, un‐
553       less  a  instance profile has been set for the web context (see section
554       on InDom profiles below).
555
556         $ curl -s http://localhost:44322/pmapi/fetch?\
557                     names=kernel.all.load,disk.all.read | pmjson
558         {
559           "context": 348734,
560           "timestamp": 1547483646.2147431,
561           "values": [
562             {
563               "pmid": "60.2.0",
564               "name": "kernel.all.load",
565               "instances:" [
566                 { "instance": 1, "value": 0.1 },
567                 { "instance": 5, "value": 0.17 },
568                 { "instance": 15, "value": 0.22 }
569               ]
570             },
571             {
572               "pmid":"60.0.24",
573               "name":"disk.all.read",
574               "instances:" [
575                 { "instance": null, "value": 639231 }
576               ]
577             }
578           ]
579         }
580       The response fields map directly to  fields  from  the  underlying  pm‐
581       Fetch(3) sampling interface.
582
583       Numeric  metric types are represented as JSON integer or floating-point
584       values.  Strings are passed verbatim, except that non-ASCII values  are
585       replaced with a Unicode 0xFFFD replacement character code.
586
587       In backward compatibility mode the timestamp is presented as a JSON map
588       with second (sec) and microsecond (us) fields,  instead  of  using  the
589       more compact floating point representation shown above.
590
591   GET /pmapi/children - pmGetChildren(3), pmGetChildrenStatus(3)
592       ┌────────────┬────────┬────────────────────────────────────────────────┐
593       │Parameters  │  Type  │                  Explanation                   │
594       ├────────────┼────────┼────────────────────────────────────────────────┤
595       │prefix      │ string │ Metric namespace component as in PMNS(5)
596       ├────────────┼────────┼────────────────────────────────────────────────┤
597       │hostspec    │ string │ Host specification as described in PCPIntro(1)
598       │context     │ number │ Web context number (optional like hostspec)    │
599       │polltimeout │ number │ Seconds of inactivity before context closed    │
600       │client      │ string │ Request identifier sent back with response     │
601       └────────────┴────────┴────────────────────────────────────────────────┘
602       The children endpoint provides iterative namespace traversal for a con‐
603       text.  If no parameters are supplied, the response  will  describe  the
604       direct descendants of the Performance Metrics Name Space (PMNS) root.
605
606       The  prefix  parameter can be used to specify a subtree of the PMNS for
607       traversal.
608
609       The server response is a JSON document that provides the  set  of  leaf
610       and non-leaf nodes below the given namespace node or root.
611
612         $ curl -s http://localhost:44322/pmapi/children?prefix=mem | pmjson
613         {
614           "context": 348734,
615           "name": "mem",
616           "leaf": [
617             "physmem",
618             "freemem"
619           ],
620           "nonleaf": [
621             "util",
622             "numa",
623             "vmstat",
624             "buddyinfo",
625             "slabinfo",
626             "zoneinfo",
627             "ksm"
628           ]
629         }
630
631   GET /pmapi/indom - pmGetInDom(3), pmNameInDom(3), pmLookupInDom(3)
632       ┌────────────┬─────────┬────────────────────────────────────────────────┐
633       │Parameters  │  Type   │                  Explanation                   │
634       ├────────────┼─────────┼────────────────────────────────────────────────┤
635       │iname       │ string  │ Comma-separated list of instance names         │
636       │indom       │ pmInDom │ Numeric or pmInDomStr(3) instance domain       │
637       │instance    │ number  │ Comma-separated list of instance numbers       │
638       │match       │ string  │ Pattern matching style (exact, glob or regex)  │
639       │name        │ string  │ An individual metric name                      │
640       ├────────────┼─────────┼────────────────────────────────────────────────┤
641       │hostspec    │ string  │ Host specification as described in PCPIntro(1)
642       │context     │ number  │ Web context number (optional like hostspec)    │
643       │polltimeout │ number  │ Seconds of inactivity before context closed    │
644       │client      │ string  │ Request identifier sent back with response     │
645       └────────────┴─────────┴────────────────────────────────────────────────┘
646       This  request  lists  the current instances of an instance domain.  The
647       instance domain is either specified  directly  (in  numeric  or  string
648       form) or indirectly, by association with the specified metric.
649
650       The request can be further qualified with a comma-separated list of the
651       instances to report on, either by name or number,  using  the  instance
652       and iname parameters.
653
654       In the case of instance name qualifiers, these will be matched by exact
655       string comparison by default.  Alternatively, the match  parameter  can
656       be  used  to  specify  that regular expression or glob pattern matching
657       should be used instead.
658
659       The response is a JSON document that provides the instance domain meta‐
660       data as an array.
661
662         $ curl -s http://localhost:44322/pmapi/indom?\
663                     name=kernel.all.load | pmjson
664         {
665           "context": 348734,
666           "indom": "60.2",
667           "labels": {
668             "domainname": "acme.com",
669             "groupid": 1000,
670             "hostname": "www.acme.com",
671             "machineid": "295b7623b6074cc8bdbda8bf96f6930a"
672             "platform": "dev",
673             "userid": 1000
674           },
675           "instances": [
676             {
677               "instance": 1,
678               "name": "1 minute"
679               "labels": { ... },
680             },
681             {
682               "instance": 5,
683               "name": "5 minute"
684               "labels": { ... },
685             },
686             {
687               "instance": 15,
688               "name": "15 minute"
689               "labels": { ...  },
690             }
691           ]
692         }
693
694   GET /pmapi/profile - pmAddProfile(3), pmDelProfile(3)
695       ┌────────────┬─────────┬────────────────────────────────────────────────┐
696       │Parameters  │  Type   │                  Explanation                   │
697       ├────────────┼─────────┼────────────────────────────────────────────────┤
698       │iname       │ string  │ Comma-separated list of instance names         │
699       │indom       │ pmInDom │ Numeric or pmInDomStr(3) instance domain       │
700       │instance    │ number  │ Comma-separated list of instance numbers       │
701       │expr        │ string  │ One of "add" or "del" (mandatory).             │
702       │match       │ string  │ Pattern matching style (exact, glob or regex)  │
703       ├────────────┼─────────┼────────────────────────────────────────────────┤
704       │hostspec    │ string  │ Host specification as described in PCPIntro(1)
705       │context     │ number  │ Web context number (optional like hostspec)    │
706       │polltimeout │ number  │ Seconds of inactivity before context closed    │
707       │client      │ string  │ Request identifier sent back with response     │
708       └────────────┴─────────┴────────────────────────────────────────────────┘
709       Some  PMAPI  operations can be performed with an active instance domain
710       profile which restricts (filters) the set of  resulting  instances  re‐
711       turned, as described on pmAddProfile(3).
712
713         $ curl -s http://localhost:44322/pmapi/profile?\
714                     expr=add,indom=60.2,iname=1%20minute
715         { "context": 348734, "success": true }
716
717   GET /pmapi/store - pmStore(3)
718       ┌────────────┬────────┬────────────────────────────────────────────────┐
719       │Parameters  │  Type  │                  Explanation                   │
720       ├────────────┼────────┼────────────────────────────────────────────────┤
721       │iname       │ string │ Comma-separated list of instance names         │
722       │instance    │ number │ Comma-separated list of instance numbers       │
723       │name        │ string │ An individual metric name                      │
724       │value       │ (any)  │ New value for the given metric instance(s)     │
725       ├────────────┼────────┼────────────────────────────────────────────────┤
726       │hostspec    │ string │ Host specification as described in PCPIntro(1)
727       │context     │ number │ Web context number optional like hostspec)     │
728       │polltimeout │ number │ Seconds of inactivity before context closed    │
729       └────────────┴────────┴────────────────────────────────────────────────┘
730       Some  performance metrics allow their value to be modified, for example
731       to re-initialize counters or to modify control variables.
732
733       This operation takes a single metric name  to  modify,  and  optionally
734       specific  instances.  The mandatory value will be interpreted according
735       to the type of the metric being modified.
736
737       If successful, the response from these requests is a JSON  document  of
738       the form:
739
740         $ curl -s http://localhost:44322/pmapi/store?\
741                     name=pmcd.control.timeout&value=10
742         {
743           "context": 348734,
744           "success": true
745         }
746
747   GET /pmapi/derive: pmRegisterDerived(3)
748       ┌───────────┬────────┬────────────────────────────────────────────┐
749       │Parameters │  Type  │                Explanation                 │
750       ├───────────┼────────┼────────────────────────────────────────────┤
751       │expr       │ string │ Derived metric expression                  │
752       │name       │ string │ New derived metric name                    │
753       ├───────────┼────────┼────────────────────────────────────────────┤
754       │client     │ string │ Request identifier sent back with response │
755       └───────────┴────────┴────────────────────────────────────────────┘
756       Create  a  new  derived  metric, as defined by the pmRegisterDerived(3)
757       metric interface.  Derived metrics are not associated with any particu‐
758       lar  context  and  must be registered before creation (or reconnect) of
759       any context wishing to use the new metric.
760
761       This interface is one of the few that allows a POST to be used in place
762       of  a GET.  In this case the HTTP POST request body may be used to pro‐
763       vide one or more derived metrics specification  (all  at  once,  across
764       multiple lines, as a convenience).
765
766         $ curl -s http://localhost:44322/pmapi/derive?\
767                    name=blkio.avgsz&expr=disk.all.blktotal/disk.all.total | pmjson
768         {
769           "success": true
770         }
771
772         $ curl -s http://localhost:44322/pmapi/fetch?\
773                    name=blkio.avgsz&samples=2 | pmjson
774         {
775           "context": 348734,
776           "timestamp": 1547483648.2147428,
777           "values": [
778             {
779               "pmid": "511.0.27",
780               "name": "blkio.avgsz",
781               "instances:" [
782                 {
783                   "instance": null,
784                   "value": 9231
785                 }
786               ]
787             }
788           ]
789         }
790
791   GET /pmapi/metrics: pmLookupDesc(3),pmLookupLabels(3), pmFetch(3)
792       ┌────────────┬─────────┬────────────────────────────────────────────────┐
793       │Parameters  │  Type   │                  Explanation                   │
794       ├────────────┼─────────┼────────────────────────────────────────────────┤
795       │names       │ string  │ Comma-separated list of metric names           │
796       │times       │ boolean │ Append sample times (milliseconds since epoch) │
797       ├────────────┼─────────┼────────────────────────────────────────────────┤
798       │context     │ number  │ Web context number (optional like hostspec)    │
799       │hostspec    │ string  │ Host specification as described in PCPIntro(1)
800       │polltimeout │ number  │ Seconds of inactivity before context closed    │
801       │client      │ string  │ Request identifier sent back with response     │
802       └────────────┴─────────┴────────────────────────────────────────────────┘
803       This request is a subset of the style described in the ``OPEN METRICS''
804       section, allowing a web context identifier to be passed as a parameter.
805       It  is  otherwise very similar in terms of parameters and response han‐
806       dling, please refer to the earlier section for details.
807

NOTES

809       For the REST APIs, errors generally result in HTTP-level error respons‐
810       es.  Wherever possible, any PMAPI error string will also be provided in
811       a message along with the response.
812
813       All responses will be returned using HTTP 1.1 protocol and with chunked
814       encoding  being used to stream responses that are larger than a config‐
815       ured maximum size.  Compression will be used on responses whenever  the
816       client indicates appropriate support.
817
818       An  Access-Control-Allow-Origin:  * header is added to all REST API re‐
819       sponses.
820

SEE ALSO

822       PCPIntro(1),  curl(1),  pmcd(1),  pmdaopenmetrics(1),  pminfo(1),  pmj‐
823       son(1),  pmlogger(1),  pmproxy(1), pmseries(1), redis-server(1), PCPIn‐
824       tro(3) and PMAPI(3)
825
826
827
828Performance Co-Pilot                  PCP                          PMWEBAPI(3)
Impressum