-
Notifications
You must be signed in to change notification settings - Fork 0
/
sws-api-swagger.yaml
315 lines (308 loc) · 13.4 KB
/
sws-api-swagger.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
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
swagger: '2.0'
info:
version: 0.95.0
title: swagger-stats API
description: |
### Telemetry for your APIs
### Trace API calls and monitor API performance, health and usage statistics in Node.js Microservices
contact:
name: swagger-stats team
email: sv2@slana.tech
url: 'http://swaggerstats.io'
license:
name: MIT
url: 'http://opensource.org/licenses/MIT'
basePath: /
schemes:
- http
consumes:
- application/json
produces:
- application/json
paths:
/swagger-stats/stats:
get:
description: |
#### Returns statistics
operationId: /swagger-stats/stats
produces:
- application/json
parameters:
- name: fields
in: query
description: |
#### Statistics fields to return. Multiple fileds may be specified as an array
* **method** - Baseline Metrics per Requests Method
* **timeline** - Baseline Metrics collected for each 1 minute interval during last 60 minutes
* **lasterrors** - request and response details for the last 100 errors (last 100 error responses)
* **longestreq** - request and response details for top 100 requests that took longest time to process (time to send response)
* **apidefs** - API definitions froim swagger specification
* **apistats** - Baseline Metrics per each API Operation. API operation is path and method combination from the swagger spec. Swagger specification is optional. swagger-stats will detect and monitor API operations based on express routes.
* **apiop** - API Operation parameters metrics: parameter passed count, mandatory parameter missing count (for API Operation parameters defined in swagger spec)
* **errors** - Count of responses per each error code, top "not found" resources, top "server error" resources
* **all** or * - all fields
Baseline metrics are: counts of requests and responses(total and by response class), processing time (total/avg/max), content length(total/avg/max) for requests and responses, rates for requests and errors.
required: false
type: array
items:
type: string
enum:
- method
- timeline
- lasterrors
- longestreq
- apidefs
- apistats
- apiop
- errors
- all
- "*"
collectionFormat: csv
- name: path
in: query
description: |
#### Path of API Operation, to get statistics on individual API Operation. Use when field apiop is specified.
Example:
##### fields=apiop&method=GET&path=/v2/pet/{petId}
required: false
type: string
- name: method
in: query
description: |
#### Method of API Operation, to get statistics on individual API Operation. Use when field apiop is specified.
Example:
##### fields=apiop&method=GET&path=/v2/pet/{petId}
required: false
type: string
responses:
'200':
description: Statistcs
schema:
$ref: '#/definitions/stats'
'403':
description: Authentication required (if Authentication is enabled by configuration)
default:
description: unexpected error
/swagger-stats/metrics:
get:
description: |
#### Returns Prometheus Metrics. The following metrics are provided:
|Name |Type |Labels |Description
|:--------------|:--------|:----------|:----------
|`api_all_request_total`|counter|-|The total number of all API requests received|
|`api_all_success_total`|counter|-|The total number of all API requests with success response|
|`api_all_errors_total`|counter|-|The total number of all API requests with error response|
|`api_all_client_error_total`|counter|-|The total number of all API requests with client error response|
|`api_all_server_error_total`|counter|-|The total number of all API requests with server error response|
|`api_all_request_in_processing_total`|gauge|-|The total number of all API requests currently in processing (no response yet)|
|`nodejs_process_memory_rss_bytes`|gauge|-|Node.js process resident memory (RSS) bytes|
|`nodejs_process_memory_heap_total_bytes`|gauge|-|Node.js process memory heapTotal bytes|
|`nodejs_process_memory_heap_used_bytes`|gauge|-|Node.js process memory heapUsed bytes|
|`nodejs_process_memory_external_bytes`|gauge|-|Node.js process memory external bytes|
|`nodejs_process_cpu_usage_percentage`|gauge|-|Node.js process CPU usage percentage|
|`api_request_total`|counter|method<br/>path<br/>code|The total number of all API requests|
|`api_request_duration_milliseconds`|histogram|method<br/>path<br/>le|API requests duration|
|`api_request_size_bytes`|histogram|method<br/>path<br/>le|API requests size|
|`api_response_size_bytes`|histogram|method<br/>path<br/>le|API response size|
operationId: /swagger-stats/metrics
produces:
- text/plain
responses:
'200':
description: Prometheus Metrics
schema:
type: string
example: |
# HELP api_all_request_total The total number of all API requests received
# TYPE api_all_request_total counter
api_all_request_total 80
. . . .
# HELP api_request_total The total number of all API requests
# TYPE api_request_total counter
api_request_total{method="GET",path="/v2/pet/{petId}",code="200"} 1
api_request_total{method="GET",path="/v2/pet/{petId}",code="302"} 1
. . . .
# HELP api_request_duration_milliseconds API requests duration
# TYPE api_request_duration_milliseconds histogram
api_request_duration_milliseconds_bucket{method="GET",path="/v2/pet/{petId}",le="5"} 3
api_request_duration_milliseconds_bucket{method="GET",path="/v2/pet/{petId}",le="10"} 3
api_request_duration_milliseconds_bucket{method="GET",path="/v2/pet/{petId}",le="25"} 4
api_request_duration_milliseconds_bucket{method="GET",path="/v2/pet/{petId}",le="50"} 4
api_request_duration_milliseconds_bucket{method="GET",path="/v2/pet/{petId}",le="100"} 4
api_request_duration_milliseconds_bucket{method="GET",path="/v2/pet/{petId}",le="250"} 4
api_request_duration_milliseconds_bucket{method="GET",path="/v2/pet/{petId}",le="500"} 4
api_request_duration_milliseconds_bucket{method="GET",path="/v2/pet/{petId}",le="1000"} 4
api_request_duration_milliseconds_bucket{method="GET",path="/v2/pet/{petId}",le="2500"} 4
api_request_duration_milliseconds_bucket{method="GET",path="/v2/pet/{petId}",le="5000"} 4
api_request_duration_milliseconds_bucket{method="GET",path="/v2/pet/{petId}",le="10000"} 4
api_request_duration_milliseconds_bucket{method="GET",path="/v2/pet/{petId}",le="+Inf"} 4
api_request_duration_milliseconds_count{method="GET",path="/v2/pet/{petId}"} 4
api_request_duration_milliseconds_sum{method="GET",path="/v2/pet/{petId}"} 12
. . . .
'403':
description: Authentication required (if Authentication is enabled by configuration)
default:
description: unexpected error
/swagger-stats/logout:
get:
description: Logout user (if Authentication is enabled by configuration)
operationId: /swagger-stats/logout
responses:
'200':
description: User logged out
default:
description: unexpected error
definitions:
baselinestats:
type: object
description: |
Baseline statistics object. Provides core metrics on request-reponse processing. Baseline statistics are calculated in in several different contexts.
* `all` stats contains total values for all requests and responses
* In `timeline`, each bucket contains baseline stats calculated for a time interval
* In `method` baseline stats are calculated per each request method
* `apistats` provides baseline stats per each API Operation
properties:
requests:
type: integer
description: Total number of requests received
responses:
type: integer
description: Total number of responses sent
errors:
type: integer
description: Total number of error responses
info:
type: integer
description: Total number of informational responses
success:
type: integer
description: Total number of success responses
redirect:
type: integer
description: Total number of redirection responses
client_error:
type: integer
description: Total number of client error responses
server_error:
type: integer
description: Total number of server error responses
total_time:
type: integer
description: Sum of total processing time (from request received to response finished)
max_time:
type: integer
description: Maximum observed processed time
avg_time:
type: number
description: Average processing time
total_req_clength:
type: integer
description: Total (Sum) of Content Lengths of received requests
max_req_clength:
type: integer
description: Maximum observed Content length in received requests
avg_req_clength:
type: number
description: Average Content Length in received requests
total_res_clength:
type: integer
description: Total (Sum) of Content Lengths of sent responses
max_res_clength:
type: integer
description: Maximum observed Content Length in sent responses
avg_res_clength:
type: number
description: Average Content Length in sent responses
req_rate:
type: number
description: Request Rate
err_rate:
type: number
description: Error Rate
apdex_threshold:
type: number
description: Current Apdex threshold
apdex_satisfied:
type: number
description: Total number of `satisfied` requests - success and response time <= apdex_threshold
apdex_tolerated:
type: number
description: Total number of `tolerated` requests - success and response time <= apdex_threshold
apdex_score:
type: number
description: Apdex score - (apdex_satisfied + (apdex_tolerated/2))/responses
sysstats:
type: object
description: System statistics - memory usage and CPU usage of node process. As returned by process.memoryUsage() and process.cpuUsage().
properties:
rss:
type: integer
description: Memory Usage - Resident Set Size, as returned by process.memoryUsage()
heapTotal:
type: integer
description: Memory Usage - Total Size of the Heap, as returned by process.memoryUsage()
heapUsed:
type: integer
description: Memory Usage - Heap actually Used, as returned by process.memoryUsage()
external:
type: integer
description: Memory Usage - External memory, as returned by process.memoryUsage()
cpu:
type: integer
description: CPU Usage % - as returned by process.cpuUsage(), calculated per [https://github.com/nodejs/node/pull/6157](https://github.com/nodejs/node/pull/6157)
methods:
type: object
description: Statistics per request method
properties:
GET:
$ref: '#/definitions/baselinestats'
POST:
$ref: '#/definitions/baselinestats'
PUT:
$ref: '#/definitions/baselinestats'
DELETE:
$ref: '#/definitions/baselinestats'
additionalProperties:
$ref: '#/definitions/baselinestats'
stats:
type: object
description: Stats object is returned by /stats API. It always inlcudes main properties (`startts`, `name`, `version`, `hostname`, `ip`), `all` statistics, and `sys' statistics. Depending on parameters passed to /stats API call, additional statistics properties will be included as well.
required:
- startts
- all
- sys
- name
- version
- hostname
- ip
- apdexThreshold
properties:
startts:
type: integer
format: int64
description: timestamp when collection of statistic started - application start time
name:
type: string
description: Name
version:
type: string
description: Version
hostname:
type: string
description: Hostname
ip:
type: string
description: IP address
apdexThreshold:
type: string
description: |
Current Apdex Threshold, in milliseconds. Default: `25`.
In Apdex calculation, request considered Satisfied if it is answered in less then this Threshold (< 25ms),
and request is Tolerating if it's answered in less then Threshold * 4 (<100 ms)
See [Apdex calculation](https://en.wikipedia.org/wiki/Apdex)
all:
$ref: '#/definitions/baselinestats'
sys:
$ref: '#/definitions/sysstats'
methods:
$ref: '#/definitions/methods'