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
9
10

OVERVIEW

12       The PMWEBAPI interface is a binding of a subset of  the  PMAPI  to  the
13       web.   It  uses  HTTP  as  transport,  REST as organizational style for
14       request/parameter encoding (the GET and POST methods  are  interchange‐
15       able),  and JSON as response encoding.  A context identifier is used as
16       a persistent  way  to  refer  to  PMAPI  contexts  across  related  web
17       requests.  These context identifiers expire after a configurable period
18       of disuse.
19
20       Errors generally result in  HTTP-level  error  responses.   An  Access-
21       Control-Allow-Origin: * header is added to all JSON responses.
22
23

CONTEXT CREATION: pmNewContext

25       To create a new web context identifier, a web client invokes:
26
27       /pmapi/context?hostname=STRING
28
29       /pmapi/context?hostspec=STRING
30              Creates a PM_CONTEXT_HOST PMAPI context with the given host name
31              and/or extended specification.  If the host  specification  con‐
32              tains  a  userid/password  combination,  then  the corresponding
33              PMAPI context operations will require HTTP Basic  authentication
34              credentials with matching userid/password.
35
36       In addition, the web client may add the parameter &polltimeout=MMMM for
37       a maximum interval (in seconds) between expected accesses to the  given
38       context.  This value is limited by pmwebd configuration, and is a cour‐
39       tesy to allow pmwebd to free up memory earlier in case  of  sudden  web
40       application shutdown.
41
42       If  successful,  the response from these requests is a JSON document of
43       the form:
44
45         { "context" : NNNNN }
46
47       The number (a 32-bit unsigned decimal) is then used in all later opera‐
48       tions.
49
50

CONTEXT CREATION: configurable permanent contexts

52       In addition, permanent contexts may be created by pmwebd at initializa‐
53       tion using its -h, -a, -L command line options, so that a set of  fixed
54       NNNNN numbers may be made available to web clients.
55
56

PMAPI OPERATIONS

58       The  general form of the requests is as follows: /pmapi/NNNNN/OPERATION
59       where
60
61       /pmapi is the fixed prefix for all PMWEBAPI operations,
62
63       NNNNN  is a PMWEBAPI context number returned  from  a  context-creation
64              call, or assigned permanently at pmwebd startup, and
65
66       OPERATION?PARAM1=VALUE2&PARAM2=VALUE2
67              identifies  the  operation and its URL-encoded parameters.  Some
68              parameters may be optional.
69
70
71   METRIC METADATA: pmLookupName, pmLookupDesc, pmLookupText, pmTraversePMNS_r
72       The general form of the requests is as follows:
73
74       /pmapi/NNNNN/_metric
75              Traverse the entire Performance Metrics Name Space (PMNS).
76
77       /pmapi/NNNNN/_metric?prefix=NAME
78              Traverse the subtree of PMNS with the prefix NAME.
79
80       The response is a JSON document that provides the metric metadata as an
81       array.  For example:
82
83         { "metrics": [
84             { "name":"foo.bar", "pmID":PPPP, "indom":DDDD,
85               "type":"32", "sem":"instant", "units":"MHz",
86               "text-oneline":"foo bar", "text-help":"blah blah blah" },
87             { "name":"foo.bar2", ... }
88             ...
89           ] }
90
91       Most of the fields are self-explanatory.
92
93       name   A  name for the metric as defined in the PMNS.  If the PMNS con‐
94              tains multiple names associated with  the  metric's  Performance
95              Metric  Identifier  (PMID),  one  of  these will be returned via
96              name, but there is no way to determine which  of  the  duplicate
97              names this will be.
98
99       PPPP   the PMID
100
101       DDDD   the instance domain
102
103       type   from pmTypeStr
104
105       units  from pmUnitsStr
106
107       sem    an abbreviation of the metric semantic:
108
109              PM_SEM_COUNTER  "counter"
110              PM_SEM_INSTANT  "instant"
111              PM_SEM_DISCRETE "discrete"
112
113
114   METRIC VALUE: pmFetch
115       The general form of the requests is as follows:
116
117       /pmapi/NNNNN/_fetch?names=NAME1,NAME2
118              Fetch current values for given named metrics.
119
120       /pmapi/NNNNN/_fetch?pmids=PPPP1,PPPP2
121              Fetch current values for given PMIDs.
122
123       If  any  of  the names/pmids are valid, the response is a JSON document
124       that provides the values for all requested metrics, for all  their  in‐
125       stances.
126
127         { "timestamp": { "s":SEC, "us":USEC },
128           "values": [
129                 { "pmid":PPPP1, "name":"NAME1",
130                   "instances:" [
131                        { "instance":IIII1, "value":VALUE1 }
132                        { "instance":IIII2, "value":VALUE2 }
133                        ...
134                   ] },
135                 { "pmid":PPPP2, "name":"NAME2", ... }
136                 ...
137           ] }
138
139       Most of the fields are self-explanatory.  Numeric metric types are rep‐
140       resented as JSON integer or floating-point values.  Strings are  passed
141       verbatim,  except  that  non-ASCII  values  are replaced with a Unicode
142       0xFFFD REPLACEMENT CHARACTER code.  Event type metrics are not current‐
143       ly supported.
144
145
146   INSTANCE DOMAINS METADATA: pmGetInDom, pmNameInDom, pmLookupInDom
147       The general form of the requests is as follows:
148
149       /pmapi/NNNN/_indom?indom=DDDD
150              List instances of the given instance domain.
151
152       /pmapi/NNNN/_indom?name=NAME
153              List  instances  of  the  instance domain belonging to the named
154              metric.
155
156       In addition, either query may be suffixed with:
157
158       &instance=IIII,JJJJ
159              Restrict listings to given instance code numbers.
160
161       &iname=INAME1,INAME2
162              Restrict listings to given instance names.
163
164       The response is a JSON document that provides the metric metadata as an
165       array.  For example:
166
167         { "indom":DDDD,
168            "instances": [
169               { "instance":IIII, "name":"INAME" }
170               ...
171            ] }
172
173
174   INSTANCE PROFILE: pmAddProfile, pmDelProfile
175       The general form of these requests is as follows:
176
177       /pmapi/NNNN/_profile_reset?indom=DDDD
178              These are not currently supported.
179
180       /pmapi/NNNN/_profile_add?indom=DDDD&instance=IIII,JJJJ
181              These are not currently supported.
182
183       /pmapi/NNNN/_profile_add?indom=DDDD&iname=IIII,JJJJ
184              These are not currently supported.
185
186       /pmapi/NNNN/_profile_del?indom=DDDD&instance=JJJJ
187              These are not currently supported.
188
189       /pmapi/NNNN/_profile_del?indom=DDDD&iname=INAME1,INAME2
190              These are not currently supported.
191
192
193   METRIC STORE: pmStore
194       The general form of these requests is as follows:
195
196       /pmapi/NNNN/_store?name=NAME&value=VALUE
197              Store a new value for given named metrics.
198
199       /pmapi/NNNNN/_store?pmid=PPPP&value=VALUE
200              Store  a  new  value  for  given  performance  metric identifier
201              (PMID).
202
203       In addition, either query may be suffixed with:
204
205       &instance=IIII,JJJJ
206              Restrict store to given instance code numbers.
207
208       &iname=INAME1,INAME2
209              Restrict store to given instance names.
210
211       If successful, the response from these requests is a JSON  document  of
212       the form:
213
214         { "success" : true }
215
216
217   DERIVED METRICS: pmRegisterDerived
218       /pmapi/NNNNN/_derive?name=NAME&expr=EXPRESSION
219              These are not currently supported.
220
221
222   CONTEXT COPY: pmDupContext
223       /pmapi/NNNNN/copy
224              These are not currently supported.
225
226
227   CONTEXT CLOSE: pmDestroyContext
228       /pmapi/NNNNN/destroy
229              This  is  not  likely  to be supported, as it is destructive and
230              would offer a tempting target  to  brute-force  attackers.   In‐
231              stead,  the  pmwebd timeout is used to automatically free unused
232              contexts.
233
234
235   PROMETHEUS
236       Prometheus exporting of live metrics from a preexisting  PMWEBAPI  con‐
237       text is available:
238
239       The general form of the requests is:
240
241       /pmapi/NNNNN/metrics?target=NAME1,NAME2,...
242              Fetch current values for given named metrics.
243
244       For  all  numeric  metrics  with  the  given  NAME  prefixes,  create a
245       prometheus text export format giving their current  value  and  related
246       metadata.   The  response  has text/plain type rather than JSON, and is
247       designed to be ingested by  a  Prometheus  server,  or  pcp's  own  pm‐
248       daprometheus.
249
250       The  native  PCP metric metadata (metric name, semantics and units) are
251       first output with the # PCP prefix.  If the units string is empty, then
252       none  is  output.  The units metadata string may contain spaces and ex‐
253       tends to the end of the line.  Prometheus metric types are heuristical‐
254       ly  inferred  from  PCP metric types, and units/scales are converted to
255       base seconds/bytes/count if possible, with a corresponding suffix added
256       to  the  metric  name.   PCP  metric names are mapped so that . are ex‐
257       changed  with  :.   Instance  domain  instances  are   represented   as
258       Prometheus labels with quoted instance names.
259
260         # PCP proc.nprocs instant none
261         # HELP proc:nprocs instantaneous number of processes
262         # TYPE proc:nprocs gauge
263         proc:nprocs 7
264
265         # PCP kernel.pernode.cpu.intr counter millisec
266         # HELP kernel:pernode:cpu:intr_seconds_total total interrupt CPU time from /proc/stat for each node
267         # TYPE kernel:pernode:cpu:intr_seconds_total counter
268         kernel:pernode:cpu:intr_seconds_total{instance="node0"} 25603.540000000001
269
270         # PCP filesys.blocksize instant byte
271         # HELP filesys:blocksize_bytes Size of each block on mounted filesystem (Bytes)
272         # TYPE filesys:blocksize_bytes gauge
273         filesys:blocksize_bytes{instance="/dev/mapper/docker-253:0-83713-\
274         9a130460b46163fcf4443710db3159dea6bb5ec2aaca108515839a7a28c191ce"} 4096
275         filesys:blocksize_bytes{instance="/dev/mapper/VolGroup00-root17"} 4096
276
277
278

GRAPHITE

280       When  enabled,  pmwebd  can emulate a subset of the graphite web-api to
281       allow web applications like graphite and grafana to extract  data  from
282       all archives under the configured -A directory.  The graphite namespace
283       is constructed from the PCP archives using a simple  mapping  that  en‐
284       codes  the  Cartesian product of archives, metrics, and instance-domain
285       instances into dot-separated strings.   Some  metacharacter-quoting  is
286       employed  to  encode general strings into components.  Only numeric PCP
287       metrics are exposed; COUNTER semantic values are rate-converted.
288
289
290     ┌─────────┬────────┬───────────────────────────────────────────────────────┐
291     │position │ number │                        purpose                        │
292     ├─────────┼────────┼───────────────────────────────────────────────────────┤
293     │   1     │   1    │ encoded pathname of the archive .meta file (default), │
294     │         │        │ or canonicalized archive hostname (-J mode)           │
295     │   2     │   N    │ the N components of the pcp metric name               │
296     │  N+2    │   1    │ instance name of the metric (if any)                  │
297     └─────────┴────────┴───────────────────────────────────────────────────────┘
298       Since glob wildcarding is supported within metric name components,  us‐
299       ing  them in the first component (an encoding of the archive name) is a
300       good way to identify machines, or to match multiple  archives  spanning
301       times of interest.
302
303       We  list here only the broadest outline of the supported calls.  pmwebd
304       does not support every graphite web-api option, so many querystring pa‐
305       rameters  may  be ignored.  Arithmetic/statistical functions on metrics
306       are not supported.
307
308
309       /graphite/render?format=json&target=FOO&from=TIME&until=TIME
310              Return a series of values of the given metrics, between the  two
311              times, sampled every 60 seconds.
312
313       /graphite/rawdata?target=FOO.BAR&from=TIME&until=TIME
314              Same, with a slightly different result encoding.
315
316       /graphite/render?format=png&target=FOO&from=TIME&until=TIME&....
317              Same, but render the curves into a PNG image file.  Several col‐
318              or- and rendering-control-related parameters are supported.
319
320       /graphite/metrics/find?query=FOO.BAR.*
321              Provide incremental metric-tree traversal using wildcards.
322
323       /graphite/graphlot/findmetric?query=FOO+BAR
324              Search through metrics with space-separated regular expressions.
325
326       /graphite/browser/search?q=FOO+BAR
327              Same, with a slightly different result encoding.
328
329
330

SEE ALSO

332       PCPIntro(1), PCPIntro(3),  pmwebd(1),  http://graphite.readthedocs.org/
333       and PMAPI(3)
334
335
336
337Performance Co-Pilot                  PCP                          PMWEBAPI(3)
Impressum