swagger-stats
Version:
API Telemetry and APM. Trace API calls and Monitor API performance, health and usage statistics in Node.js Microservices, based on express routes and Swagger (Open API) specification
316 lines (308 loc) • 13.7 kB
YAML
swagger: '2.0'
info:
version: 0.99.7
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'