1PMWEBAPI(3) Library Functions Manual PMWEBAPI(3)
2
3
4
6 PMWEBAPI - introduction to the Performance Metrics Web Application Pro‐
7 gramming Interface
8
9
10
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
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 /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
40 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
46 If successful, the response from these requests is a JSON document of
47 the form:
48
49 { "context" : NNNNN }
50
51 The number (a 32-bit unsigned decimal) is then used in all later opera‐
52 tions.
53
54
56 The general form of the requests is as follows: /pmapi/NNNNN/OPERATION
57 where
58
59 /pmapi is the fixed prefix for all PMWEBAPI operations,
60
61 NNNNN is a PMWEBAPI context number returned from a context-creation
62 call, or assigned permanently at pmwebd startup, and
63
64 OPERATION?PARAM1=VALUE2&PARAM2=VALUE2
65 identifies the operation and its URL-encoded parameters. Some
66 parameters may be optional.
67
68
69 METRIC METADATA: pmLookupName, pmLookupDesc, pmTraversePMNS_r
70 The general form of the requests is as follows:
71
72 /pmapi/NNNNN/_metric
73 Traverse the entire Performance Metrics Name Space (PMNS).
74
75 /pmapi/NNNNN/_metric?prefix=NAME
76 Traverse the subtree of PMNS with the prefix NAME.
77
78 The response is a JSON document that provides the metric metadata as an
79 array. For example:
80
81 { "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
89 Most of the fields are self-explanatory.
90
91 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
97 PPPP the PMID
98
99 DDDD the instance domain
100
101 type from pmTypeStr
102
103 units from pmUnitsStr
104
105 sem an abbreviation of the metric semantic:
106
107 PM_SEM_COUNTER "counter"
108 PM_SEM_INSTANT "instant"
109 PM_SEM_DISCRETE "discrete"
110
111
112 METRIC VALUE: pmFetch
113 The general form of the requests is as follows:
114
115 /pmapi/NNNNN/_fetch?names=NAME1,NAME2
116 Fetch current values for given named metrics.
117
118 /pmapi/NNNNN/_fetch?pmids=PPPP1,PPPP2
119 Fetch current values for given PMIDs.
120
121 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
125 { "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
137 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
143
144 INSTANCE DOMAINS METADATA: pmGetInDom, pmNameInDom, pmLookupInDom
145 The general form of the requests is as follows:
146
147 /pmapi/NNNN/_indom?indom=DDDD
148 List instances of the given instance domain.
149
150 /pmapi/NNNN/_indom?name=NAME
151 List instances of the instance domain belonging to the named
152 metric.
153
154 In addition, either query may be suffixed with:
155
156 &instance=IIII,JJJJ
157 Restrict listings to given instance code numbers.
158
159 &iname=INAME1,INAME2
160 Restrict listings to given instance names.
161
162 The response is a JSON document that provides the metric metadata as an
163 array. For example:
164
165 { "indom":DDDD,
166 "instances": [
167 { "instance":IIII, "name":"INAME" }
168 ...
169 ] }
170
171
172 INSTANCE PROFILE: pmAddProfile, pmDelProfile
173 The general form of these requests is as follows:
174
175 /pmapi/NNNN/_profile_reset?indom=DDDD
176 These are not currently supported.
177
178 /pmapi/NNNN/_profile_add?indom=DDDD&instance=IIII,JJJJ
179 These are not currently supported.
180
181 /pmapi/NNNN/_profile_add?indom=DDDD&iname=IIII,JJJJ
182 These are not currently supported.
183
184 /pmapi/NNNN/_profile_del?indom=DDDD&instance=JJJJ
185 These are not currently supported.
186
187 /pmapi/NNNN/_profile_del?indom=DDDD&iname=INAME1,INAME2
188 These are not currently supported.
189
190
191 METRIC STORE: pmStore
192 The general form of these requests is as follows:
193
194 /pmapi/NNNN/_store?name=NAME&value=VALUE
195 Store a new value for given named metrics.
196
197 /pmapi/NNNNN/_store?pmid=PPPP&value=VALUE
198 Store a new value for given performance metric identifier
199 (PMID).
200
201 In addition, either query may be suffixed with:
202
203 &instance=IIII,JJJJ
204 Restrict store to given instance code numbers.
205
206 &iname=INAME1,INAME2
207 Restrict store to given instance names.
208
209 If successful, the response from these requests is a JSON document of
210 the form:
211
212 { "success" : true }
213
214
215 DERIVED METRICS: pmRegisterDerived
216 /pmapi/NNNNN/_derive?name=NAME&expr=EXPRESSION
217 These are not currently supported.
218
219
220 CONTEXT COPY: pmDupContext
221 /pmapi/NNNNN/copy
222 These are not currently supported.
223
224
225 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
232
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
243
244 ┌─────────┬────────┬─────────────────────────────────────────┐
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
256 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
261
262 /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
266 /graphite/rawdata&target=FOO.BAR&from=TIME&until=TIME
267 Same, with a slightly different result encoding.
268
269 /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
273 /graphite/metrics/find&query=FOO.BAR.*
274 Provide incremental metric-tree traversal uwing wildcards.
275
276 /graphite/graphlot/findmetric&query=FOO+BAR
277 Search through metrics with space-separated regular expressions.
278
279 /graphite/browser/search&q=FOO+BAR
280 Same, with a slightly different result encoding.
281
282
283
285 PCPIntro(1), PCPIntro(3), pmwebd(1), http://graphite.readthedocs.org/
286 and PMAPI(3)
287
288
289
290Performance Co-Pilot PCP PMWEBAPI(3)