1PMWEBAPI(3) Library Functions Manual PMWEBAPI(3)
2
6 PMWEBAPI - introduction to the Performance Metrics Web Application Pro‐
7 gramming Interface
8
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 Errors generally result in HTTP-level error responses. An Access-
21 Control-Allow-Origin: * header is added to all JSON responses.
22
25 To create a new web context identifier, a web client invokes:
26 /pmapi/context?hostname=STRING
28 /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 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 If successful, the response from these requests is a JSON document of
43 the form:
44 { "context" : NNNNN }
46 The number (a 32-bit unsigned decimal) is then used in all later opera‐
48 tions.
49
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
58 The general form of the requests is as follows: /pmapi/NNNNN/OPERATION
59 where
60 /pmapi is the fixed prefix for all PMWEBAPI operations,
62 NNNNN is a PMWEBAPI context number returned from a context-creation
64 call, or assigned permanently at pmwebd startup, and
65 OPERATION?PARAM1=VALUE2&PARAM2=VALUE2
67 identifies the operation and its URL-encoded parameters. Some
68 parameters may be optional.
69 METRIC METADATA: pmLookupName, pmLookupDesc, pmLookupText, pmTraversePMNS_r
72 The general form of the requests is as follows:
73 /pmapi/NNNNN/_metric
75 Traverse the entire Performance Metrics Name Space (PMNS).
76 /pmapi/NNNNN/_metric?prefix=NAME
78 Traverse the subtree of PMNS with the prefix NAME.
79 The response is a JSON document that provides the metric metadata as an
81 array. For example:
82 { "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 Most of the fields are self-explanatory.
92 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 PPPP the PMID
100 DDDD the instance domain
102 type from pmTypeStr
104 units from pmUnitsStr
106 sem an abbreviation of the metric semantic:
108 PM_SEM_COUNTER "counter"
110 PM_SEM_INSTANT "instant"
111 PM_SEM_DISCRETE "discrete"
112 METRIC VALUE: pmFetch
115 The general form of the requests is as follows:
116 /pmapi/NNNNN/_fetch?names=NAME1,NAME2
118 Fetch current values for given named metrics.
119 /pmapi/NNNNN/_fetch?pmids=PPPP1,PPPP2
121 Fetch current values for given PMIDs.
122 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 { "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 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 INSTANCE DOMAINS METADATA: pmGetInDom, pmNameInDom, pmLookupInDom
147 The general form of the requests is as follows:
148 /pmapi/NNNN/_indom?indom=DDDD
150 List instances of the given instance domain.
151 /pmapi/NNNN/_indom?name=NAME
153 List instances of the instance domain belonging to the named
154 metric.
155 In addition, either query may be suffixed with:
157 &instance=IIII,JJJJ
159 Restrict listings to given instance code numbers.
160 &iname=INAME1,INAME2
162 Restrict listings to given instance names.
163 The response is a JSON document that provides the metric metadata as an
165 array. For example:
166 { "indom":DDDD,
168 "instances": [
169 { "instance":IIII, "name":"INAME" }
170 ...
171 ] }
172 INSTANCE PROFILE: pmAddProfile, pmDelProfile
175 The general form of these requests is as follows:
176 /pmapi/NNNN/_profile_reset?indom=DDDD
178 These are not currently supported.
179 /pmapi/NNNN/_profile_add?indom=DDDD&instance=IIII,JJJJ
181 These are not currently supported.
182 /pmapi/NNNN/_profile_add?indom=DDDD&iname=IIII,JJJJ
184 These are not currently supported.
185 /pmapi/NNNN/_profile_del?indom=DDDD&instance=JJJJ
187 These are not currently supported.
188 /pmapi/NNNN/_profile_del?indom=DDDD&iname=INAME1,INAME2
190 These are not currently supported.
191 METRIC STORE: pmStore
194 The general form of these requests is as follows:
195 /pmapi/NNNN/_store?name=NAME&value=VALUE
197 Store a new value for given named metrics.
198 /pmapi/NNNNN/_store?pmid=PPPP&value=VALUE
200 Store a new value for given performance metric identifier
201 (PMID).
202 In addition, either query may be suffixed with:
204 &instance=IIII,JJJJ
206 Restrict store to given instance code numbers.
207 &iname=INAME1,INAME2
209 Restrict store to given instance names.
210 If successful, the response from these requests is a JSON document of
212 the form:
213 { "success" : true }
215 DERIVED METRICS: pmRegisterDerived
218 /pmapi/NNNNN/_derive?name=NAME&expr=EXPRESSION
219 These are not currently supported.
220 CONTEXT COPY: pmDupContext
223 /pmapi/NNNNN/copy
224 These are not currently supported.
225 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 PROMETHEUS
236 Prometheus exporting of live metrics from a preexisting PMWEBAPI con‐
237 text is available:
238 The general form of the requests is:
240 /pmapi/NNNNN/metrics?target=NAME1,NAME2,...
242 Fetch current values for given named metrics.
243 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 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 # PCP proc.nprocs instant none
261 # HELP proc:nprocs instantaneous number of processes
262 # TYPE proc:nprocs gauge
263 proc:nprocs 7
264 # 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 # 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
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 ┌─────────┬────────┬───────────────────────────────────────────────────────┐
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 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 /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 /graphite/rawdata?target=FOO.BAR&from=TIME&until=TIME
314 Same, with a slightly different result encoding.
315 /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 /graphite/metrics/find?query=FOO.BAR.*
321 Provide incremental metric-tree traversal using wildcards.
322 /graphite/graphlot/findmetric?query=FOO+BAR
324 Search through metrics with space-separated regular expressions.
325 /graphite/browser/search?q=FOO+BAR
327 Same, with a slightly different result encoding.
328
332 PCPIntro(1), PCPIntro(3), pmwebd(1), http://graphite.readthedocs.org/
333 and PMAPI(3)
334Performance Co-Pilot PCP PMWEBAPI(3)