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 /pmapi/context?archivefile=ARCHIVE
37 Creates a PM_CONTEXT_ARCHIVE PMAPI context with the given file
38 name. Only metrics from the given archive are available.
39 In addition, the web client may add the parameter &polltimeout=MMMM for
41 a maximum interval (in seconds) between expected accesses to the given
42 context. This value is limited by pmwebd configuration, and is a cour‐
43 tesy to allow pmwebd to free up memory earlier in case of sudden web
44 application shutdown.
45 If successful, the response from these requests is a JSON document of
47 the form:
48 { "context" : NNNNN }
50 The number (a 32-bit unsigned decimal) is then used in all later opera‐
52 tions.
53
56 The general form of the requests is as follows: /pmapi/NNNNN/OPERATION
57 where
58 /pmapi is the fixed prefix for all PMWEBAPI operations,
60 NNNNN is a PMWEBAPI context number returned from a context-creation
62 call, or assigned permanently at pmwebd startup, and
63 OPERATION?PARAM1=VALUE2&PARAM2=VALUE2
65 identifies the operation and its URL-encoded parameters. Some
66 parameters may be optional.
67 METRIC METADATA: pmLookupName, pmLookupDesc, pmTraversePMNS_r
70 The general form of the requests is as follows:
71 /pmapi/NNNNN/_metric
73 Traverse the entire Performance Metrics Name Space (PMNS).
74 /pmapi/NNNNN/_metric?prefix=NAME
76 Traverse the subtree of PMNS with the prefix NAME.
77 The response is a JSON document that provides the metric metadata as an
79 array. For example:
80 { "metrics": [
82 { "name":"foo.bar", "pmID":PPPP, "indom":DDDD,
83 "type":"32", "sem":"instant", "units":"MHz",
84 "text-oneline":"foo bar", "text-help":"blah blah blah" },
85 { "name":"foo.bar2", ... }
86 ...
87 ] }
88 Most of the fields are self-explanatory.
90 name A name for the metric as defined in the PMNS. If the PMNS con‐
92 tains multiple names associated with the metric's Performance
93 Metric Identifier (PMID), one of these will be returned via
94 name, but there is no way to determine which of the duplicate
95 names this will be.
96 PPPP the PMID
98 DDDD the instance domain
100 type from pmTypeStr
102 units from pmUnitsStr
104 sem an abbreviation of the metric semantic:
106 PM_SEM_COUNTER "counter"
108 PM_SEM_INSTANT "instant"
109 PM_SEM_DISCRETE "discrete"
110 METRIC VALUE: pmFetch
113 The general form of the requests is as follows:
114 /pmapi/NNNNN/_fetch?names=NAME1,NAME2
116 Fetch current values for given named metrics.
117 /pmapi/NNNNN/_fetch?pmids=PPPP1,PPPP2
119 Fetch current values for given PMIDs.
120 If any of the names/pmids are valid, the response is a JSON document
122 that provides the values for all requested metrics, for all their in‐
123 stances.
124 { "timestamp": { "s":SEC, "us":USEC },
126 "values": [
127 { "pmid":PPPP1, "name":"NAME1",
128 "instances:" [
129 { "instance":IIII1, "value":VALUE1 }
130 { "instance":IIII2, "value":VALUE2 }
131 ...
132 ] },
133 { "pmid":PPPP2, "name":"NAME2", ... }
134 ...
135 ] }
136 Most of the fields are self-explanatory. Numeric metric types are rep‐
138 resented as JSON integer or floating-point values. Strings are passed
139 verbatim, except that non-ASCII values are replaced with a Unicode
140 0xFFFD REPLACEMENT CHARACTER code. Event type metrics are not current‐
141 ly supported.
142 INSTANCE DOMAINS METADATA: pmGetInDom, pmNameInDom, pmLookupInDom
145 The general form of the requests is as follows:
146 /pmapi/NNNN/_indom?indom=DDDD
148 List instances of the given instance domain.
149 /pmapi/NNNN/_indom?name=NAME
151 List instances of the instance domain belonging to the named
152 metric.
153 In addition, either query may be suffixed with:
155 &instance=IIII,JJJJ
157 Restrict listings to given instance code numbers.
158 &iname=INAME1,INAME2
160 Restrict listings to given instance names.
161 The response is a JSON document that provides the metric metadata as an
163 array. For example:
164 { "indom":DDDD,
166 "instances": [
167 { "instance":IIII, "name":"INAME" }
168 ...
169 ] }
170 INSTANCE PROFILE: pmAddProfile, pmDelProfile
173 The general form of these requests is as follows:
174 /pmapi/NNNN/_profile_reset?indom=DDDD
176 These are not currently supported.
177 /pmapi/NNNN/_profile_add?indom=DDDD&instance=IIII,JJJJ
179 These are not currently supported.
180 /pmapi/NNNN/_profile_add?indom=DDDD&iname=IIII,JJJJ
182 These are not currently supported.
183 /pmapi/NNNN/_profile_del?indom=DDDD&instance=JJJJ
185 These are not currently supported.
186 /pmapi/NNNN/_profile_del?indom=DDDD&iname=INAME1,INAME2
188 These are not currently supported.
189 METRIC STORE: pmStore
192 The general form of these requests is as follows:
193 /pmapi/NNNN/_store?name=NAME&value=VALUE
195 Store a new value for given named metrics.
196 /pmapi/NNNNN/_store?pmid=PPPP&value=VALUE
198 Store a new value for given performance metric identifier
199 (PMID).
200 In addition, either query may be suffixed with:
202 &instance=IIII,JJJJ
204 Restrict store to given instance code numbers.
205 &iname=INAME1,INAME2
207 Restrict store to given instance names.
208 If successful, the response from these requests is a JSON document of
210 the form:
211 { "success" : true }
213 DERIVED METRICS: pmRegisterDerived
216 /pmapi/NNNNN/_derive?name=NAME&expr=EXPRESSION
217 These are not currently supported.
218 CONTEXT COPY: pmDupContext
221 /pmapi/NNNNN/copy
222 These are not currently supported.
223 CONTEXT CLOSE: pmDestroyContext
226 /pmapi/NNNNN/destroy
227 This is not likely to be supported, as it is destructive and
228 would offer a tempting target to brute-force attackers. In‐
229 stead, the pmwebd timeout is used to automatically free unused
230 contexts.
231
234 When enabled, pmwebd can emulate a subset of the graphite web-api to
235 allow web applications like graphite and grafana to extract data from
236 all archives under the configured -A directory. The graphite namespace
237 is constructed from the PCP archives using a simple mapping that en‐
238 codes the Cartesian product of archives, metrics, and instance-domain
239 instances into dot-separated strings. Some metacharacter-quoting is
240 employed to encode general strings into components. Only numeric PCP
241 metrics are exposed; COUNTER semantic values are rate-converted.
242 ┌─────────┬────────┬─────────────────────────────────────────┐
245 │position │ number │ purpose │
246 ├─────────┼────────┼─────────────────────────────────────────┤
247 │ 1 │ 1 │ the pathname of the archive .meta file │
248 │ 2 │ N │ the N components of the pcp metric name │
249 │ N+2 │ 1 │ instance name of the metric (if any) │
250 └─────────┴────────┴─────────────────────────────────────────┘
251 Since glob wildcarding is supported within metric name components, us‐
252 ing them in the first component (an encoding of the archive name) is a
253 good way to identify machines, or to match multiple archives spanning
254 times of interest. Compressed archives are excluded.
255 We list here only the broadest outline of the supported calls. pmwebd
257 does not support every graphite web-api option, so many querystring pa‐
258 rameters may be ignored. Arithmetic/statistical functions on metrics
259 are not supported.
260 /graphite/render&format=json&target=FOO&from=TIME&until=TIME
263 Return a series of values of the given metrics, between the two
264 times, sampled every 60 seconds.
265 /graphite/rawdata&target=FOO.BAR&from=TIME&until=TIME
267 Same, with a slightly different result encoding.
268 /graphite/render&format=png&target=FOO&from=TIME&until=TIME&....
270 Same, but render the curves into a PNG image file. Several col‐
271 or- and rendering-control-related parameters are supported.
272 /graphite/metrics/find&query=FOO.BAR.*
274 Provide incremental metric-tree traversal uwing wildcards.
275 /graphite/graphlot/findmetric&query=FOO+BAR
277 Search through metrics with space-separated regular expressions.
278 /graphite/browser/search&q=FOO+BAR
280 Same, with a slightly different result encoding.
281
285 PCPIntro(1), PCPIntro(3), pmwebd(1), http://graphite.readthedocs.org/
286 and PMAPI(3)
287Performance Co-Pilot PCP PMWEBAPI(3)