-
Notifications
You must be signed in to change notification settings - Fork 0
/
openapi.yaml
246 lines (241 loc) · 7.4 KB
/
openapi.yaml
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
openapi: 3.1.0
info:
title: GPU measurement service
summary: API for measuring energy consumption of GPUs
version: 1.0.0
description: |
This API allows performing *measurements* within *campaigns*. A new campaing
is started via a POST to the `/v1/energy` end-point:
POST /v1/energy
The end-point will respond with a `303 See Other` status and a `Location`
header containing the URI of the end-point associated to the new campaign.
HTTP/1.1 303 See Other
Location: /v1/energy/0
Subsequent GET requests on that end-point will yield a new measurement
relative to the instant the campaign was created.
paths:
/v1/device_count:
get:
summary: Retrieve the number of devices
description: |
This request yields with the number of distinct devices (i.e. GPUs)
addressable through this service. Devices are enumerated, starting from
`0` up to, not including, this value.
responses:
'200':
description: The number of devices
content:
application/json:
schema:
type: integer
default:
$ref: '#/components/responses/error'
/v1/device/{id}/name:
get:
summary: Retrieve the name of a device
responses:
'200':
description: The name of the device
content:
application/json:
schema:
type: string
'404':
$ref: '#/components/responses/device_not_found'
default:
$ref: '#/components/responses/error'
parameters:
- $ref: '#/components/parameters/device_id'
/v1/device/{id}/uuid:
get:
summary: Retrieve the UUID of a device
responses:
'200':
description: The UUID of the device
content:
application/json:
schema:
type: string
'404':
$ref: '#/components/responses/device_not_found'
default:
$ref: '#/components/responses/error'
parameters:
- $ref: '#/components/parameters/device_id'
/v1/device/{id}/serial:
get:
summary: Retrieve the serial of a device
responses:
'200':
description: The serial of the device
content:
application/json:
schema:
type: string
'404':
$ref: '#/components/responses/device_not_found'
default:
$ref: '#/components/responses/error'
parameters:
- $ref: '#/components/parameters/device_id'
/v1/device/{id}/power_usage:
get:
summary: Retrieve the current power usage of a device
responses:
'200':
description: The current power usage of the device in mW
content:
application/json:
schema:
type: integer
'404':
$ref: '#/components/responses/device_not_found'
default:
$ref: '#/components/responses/error'
parameters:
- $ref: '#/components/parameters/device_id'
/v1/energy:
get:
summary: Perform a oneshot measurement of energy consumption
description: |
This request will perform a oneshot measurement of the devices' energy
consumption over the specified duration (in ms) or, if no duration is
specified, a default duration. The request will block for the duration
of the measurement.
This request is not availible unless the service was started with
oneshot end-points enabled. Whether or not oneshot end-points are
enabled is exposed via the health-check end-point.
responses:
'200':
$ref: '#/components/responses/measurement'
'404':
description: (Blocking) oneshot end-points are not enabled.
default:
$ref: '#/components/responses/error'
parameters:
- name: duration
in: query
description: number of ms to measure
schema:
type: integer
post:
summary: Create a new measurement campaign
description: |
This request will create a new measurement campaign and redirect to the
new campaign's end-point.
responses:
'303':
description: Redirect to the new campaign
headers:
Location:
description: URI of the new campaign
schema:
type: string
example: /v1/energy/0
default:
$ref: '#/components/responses/error'
/v1/energy/{campaign}:
get:
summary: Get a new measurement for the campaign
description: |
This request will perform a new measurement relative to the
instant in which the campaign was created.
responses:
'200':
$ref: '#/components/responses/measurement'
'404':
$ref: '#/components/responses/campaign_not_found'
default:
$ref: '#/components/responses/error'
parameters:
- $ref: '#/components/parameters/campaign_id'
delete:
summary: End a specific campaign
description: |
This request will end a campaign and free all resources associated with
it.
responses:
'200':
description: The campaign ended.
'404':
$ref: '#/components/responses/campaign_not_found'
default:
$ref: '#/components/responses/error'
parameters:
- $ref: '#/components/parameters/campaign_id'
/v1/ping:
get:
summary: Simple ping endpoint
responses:
'200':
description: Empty ping response
/v1/health:
get:
summary: Perform a health-check
responses:
'200':
description: Health data of the service
content:
application/json:
schema:
type: object
properties:
device_count:
type: integer
device_names:
type: array
items:
type: string
version:
type: string
driver_version:
type: string
nvml_version:
type: string
campaigns:
type: integer
oneshot_enabled:
type: boolean
default:
$ref: '#/components/responses/error'
components:
responses:
measurement:
description: The duration in ms and devices' energy consumptions in mJ
content:
application/json:
schema:
type: object
properties:
time:
type: integer
devices:
type: array
items:
type: object
properties:
id:
type: integer
energy:
type: integer
device_not_found:
description: A device with the provided id does not exist.
campaign_not_found:
description: A campaign with the provided id does not exist.
error:
description: Unexpected error
parameters:
device_id:
name: id
in: path
description: device id
required: true
schema:
type: integer
campaign_id:
name: id
in: path
description: campaign id
required: true
schema:
type: integer