summaryrefslogtreecommitdiff
path: root/man/man3/pmwebapi.3
blob: e4ad6f4639e077bcb165e03c3f7aa26015c76cad (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
'\" t macro stdmacro
.\"
.\" Copyright (c) 2013-2014 Red Hat, Inc.  All Rights Reserved.
.\" 
.\" This program is free software; you can redistribute it and/or modify it
.\" under the terms of the GNU General Public License as published by the
.\" Free Software Foundation; either version 2 of the License, or (at your
.\" option) any later version.
.\" 
.\" This program is distributed in the hope that it will be useful, but
.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
.\" or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
.\" for more details.
.\" 
.\" 
.TH PMWEBAPI 3 "PCP" "Performance Co-Pilot"
.SH NAME
\f3PMWEBAPI\f1 \- introduction to the Performance Metrics Web Application Programming Interface

.de SAMPLE
.br
.RS
.nf
.nh
..
.de ESAMPLE
.hy
.fi
.RE
..

.SH OVERVIEW

The PMWEBAPI interface is a binding of a subset of the PMAPI to the
web.  It uses HTTP as transport, REST as organizational style for
request/parameter encoding (the GET and POST methods are
interchangeable), and JSON as response encoding.  A context identifier
is used as a persistent way to refer to PMAPI contexts across related
web requests.  These context identifiers expire after a configurable
period of disuse.  Errors generally result in HTTP-level error responses.
An
.nh
.B Access-Control-Allow-Origin: *
.hy
header is added to all JSON responses.

.SH CONTEXT CREATION: pmNewContext

To create a new web context identifier, a web client invokes:
.TP
.B /pmapi/context?local=ANYTHING
Creates a PM_CONTEXT_LOCAL PMAPI context.
.TP
.B /pmapi/context?hostname=STRING
.TP
.B /pmapi/context?hostspec=STRING
Creates a PM_CONTEXT_HOST PMAPI context with the given host name and/or extended
specification.  If the host specification contains a userid/password combination,
then the corresponding pmapi context operations will require HTTP Basic authentication
credentials with matching userid/password.
.TP
.B /pmapi/context?archivefile=ARCHIVE
Creates a PM_CONTEXT_ARCHIVE PMAPI context with the given file name.
.PP
In addition, the web client may add the parameter
.B &polltimeout=MMMM
for a maximum interval (in seconds) between expected accesses to the
given context.  This value is limited by pmwebd configuration, and is
a courtesy to allow pmwebd to free up memory earlier in case of sudden
web application shutdown.

If successful, the response from these requests is a JSON document of the form:

.SAMPLE
{ "context" : NNNNN }
.ESAMPLE

The number (a 32-bit unsigned decimal) is then used in all later operations.

.SH PMAPI OPERATIONS

The general form of the requests is as follows:
.B /pmapi/NNNNN/OPERATION
where
.TP
.B /pmapi
is the fixed prefix for all PMWEBAPI operations,
.TP
.B NNNNN
is a PMWEBAPI context number returned from a context-creation call, or
assigned permanently at pmwebd startup, and
.TP
.B OPERATION?PARAM1=VALUE2&PARAM2=VALUE2
identifies the operation and its URL-encoded parameters.  Some
parameters may be optional.

.SS METRIC METADATA: pmLookupName, pmLookupDesc, pmTraversePMNS_r

The general form of the requests is as follows:
.TP
.B /pmapi/NNNNN/_metric
Traverse the entire PMNS.
.TP
.B /pmapi/NNNNN/_metric?prefix=NAME
Traverse the subtree of PMNS with the prefix NAME.
.PP
The response is a JSON document that provides the metric metadata
as an array.  For example:

.SAMPLE
{ "metrics": [ 
    { "name":"foo.bar", "pmID":PPPP, "indom":DDDD,
      "type":"32", "sem":"instant", "units":"MHz",
      "text-oneline":"foo bar", "text-help":"blah blah blah" },
    { "name":"foo.bar2", ... }
    ...
  ] }
.ESAMPLE

Most of the fields are self-explanatory.
.TP
PPPP
the PMID
.TP
DDDD
the instance domain
.TP
type
from pmTypeStr
.TP
units
from pmUnitsStr
.TP
sem
an abbreviation of the metric semantic:
.TS
l l.
PM_SEM_COUNTER  "counter"
PM_SEM_INSTANT  "instant"
PM_SEM_DISCRETE "discrete"
.TE

.SS METRIC VALUE: pmFetch

The general form of the requests is as follows:
.TP
.B /pmapi/NNNNN/_fetch?names=NAME1,NAME2
Fetch current values for given named metrics.
.TP
.B /pmapi/NNNNN/_fetch?pmids=PPPP1,PPPP2
Fetch current values for given PMIDs.
.PP
The response is a JSON document that provides the values for
all requested metrics, for all their instances.

.SAMPLE
{ "timestamp": { "s":SEC, "us":USEC },
  "values": [
        { "pmid":PPPP1, "name":"NAME1",
          "instances:" [
               { "instance":IIII1, "value":VALUE1 }
               { "instance":IIII2, "value":VALUE2 }
               ...
          ] },
        { "pmid":PPPP2, "name":"NAME2", ... }
        ...
  ] }
.ESAMPLE

Most of the fields are self-explanatory.  Numeric metric types
are represented as JSON integer or floating-point values.  Strings
are passed verbatim, except that non-ASCII values are replaced
with a Unicode 0xFFFD REPLACEMENT CHARACTER code.  Event type metrics
are not currently supported.

.SS INSTANCE DOMAINS METADATA: pmGetInDom, pmNameInDom, pmLookupInDom

The general form of the requests is as follows:
.TP
.B /pmapi/NNNN/_indom?indom=DDDD
List instances of the given instance domain.
.TP
.B /pmapi/NNNN/_indom?name=NAME
List instances of the instance domain belonging to the named metric.
.PP
In addition, either query may be suffixed with:
.TP
.B &instance=IIII,JJJJ
Restrict listings to given instance code numbers.
.TP
.B &iname=INAME1,INAME2
Restrict listings to given instance names.
.PP

The response is a JSON document that provides the metric metadata
as an array.  For example:

.SAMPLE
{ "indom":DDDD,
   "instances": [
      { "instance":IIII, "name":"INAME" }
      ...
   ] }
.ESAMPLE

.SS INSTANCE PROFILE: pmAddProfile, pmDelProfile

.TP
.B /pmapi/NNNN/_profile_reset?
These are not currently supported.
.TP
.B /pmapi/NNNN/_profile_reset?indom=DDDD
These are not currently supported.
.TP
.B /pmapi/NNNN/_profile_add?indom=DDDD&instance=IIII,JJJJ
These are not currently supported.
.TP
.B /pmapi/NNNN/_profile_add?indom=DDDD&iname=IIII,JJJJ
These are not currently supported.
.TP
.B /pmapi/NNNN/_profile_del?indom=DDDD&instance=JJJJ
These are not currently supported.
.TP
.B /pmapi/NNNN/_profile_del?indom=DDDD&iname=INAME1,INAME2
These are not currently supported.

.SS DERIVED METRICS: pmRegisterDerived

.TP
.B /pmapi/NNNNN/_derive?name=NAME&expr=EXPRESSION
These are not currently supported.

.SS CONTEXT COPY: pmDupContext

.TP
.B /pmapi/NNNNN/copy
These are not currently supported.

.SS CONTEXT CLOSE: pmDestroyContext

.TP
.B /pmapi/NNNNN/destroy
This is not likely to be supported, as it is destructive and would offer
a tempting target to brute-force attackers.  Instead, the pmwebd timeout
is used to automatically free unused contexts. 

.SH SEE ALSO
.BR PCPIntro (1),
.BR PCPIntro (3),
.BR pmwebd (3),
and
.BR PMAPI (3)