0.95.16 • Public • Published


    swagger-stats | API Observability

    https://swaggerstats.io | Guide

    Build Status Coverage Status npm version npm downloads Gitter

    Trace API calls and Monitor API performance, health and usage statistics in Node.js Microservices

    Express, Fastify, Koa, Hapi, Restify

    swagger-stats traces REST API requests and responses in Node.js Microservices, and collects statistics per API Operation. swagger-stats detects API operations based on express routes. You may also provide Swagger (Open API) specification, and swagger-stats will match API requests with API Operations defined in swagger specification.

    swagger-stats exposes statistics and metrics per API Operation, such as GET /myapi/:parameter, or GET /pet/{petId}

    Built-In API Telemetry

    swagger-stats provides built-in Telemetry UX, so you may enable swagger-stats in your app, and start monitoring immediately, with no infrastructure requirements. Navigate to http://<your app host:port>/swagger-stats/ux

    swagger-stats Built-In Telemetry

    API Analytics with Elasticsearch and Kibana

    swagger-stats stores details about each request/response in Elasticsearch, so you may use Kibana to perform detailed analysis of API usage over time, build visualizations and dashboards

    swagger-stats Kibana Dashboard

    See dashboards/elastic6 for swagger-stats Kibana visualizations and dashboards

    Monitoring and Alerting with Prometheus and Grafana

    swagger-stats exposes metrics in Prometheus format, so you may use Prometheus and Grafana to setup API monitoring and alerting

    swagger-stats Prometheus Dashboard

    See dashboards/prometheus for swagger-stats Grafana dashboards

    With statistics and metrics exposed by swagger-stats you may spot problematic API endpoints, see where most of errors happens, catch long-running requests, analyze details of last errors, observe trends, setup alerting.

    swagger-stats provides:

    • Metrics in Prometheus format, so you may use Prometheus and Grafana to setup API monitoring and alerting
    • Storing details about each API Request/Response in Elasticsearch, so you may use Kibana to perform analysis of API usage over time, build visualizations and dashboards
    • Built-in API Telemetry UI, so you may enable swagger-stats in your app, and start monitoring right away, with no additional tools required
    • Exposing collected statistics via API, including:
    • 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. This is baseline set of stats.
    • Statistics by Request Method: baseline stats collected for each request method
    • Timeline: baseline stats collected for each 1 minute interval during last 60 minutes. Timeline helps you to analyze trends.
    • Errors: count of responses per each error code, top "not found" resources, top "server error" resources
    • Last errors: request and response details for the last 100 errors (last 100 error responses)
    • Longest requests: request and response details for top 100 requests that took longest time to process (time to send response)
    • Tracing: Request and Response details - method, URLs, parameters, request and response headers, addresses, start/stop times and processing duration, matched API Operation info
    • API Statistics: baseline stats and parameter stats per each API Operation. API operation detected based on express routes, and based on Swagger (Open API) specification
    • CPU and Memory Usage of Node process

    How to Use


    npm install swagger-stats --save

    Enable swagger-stats middleware in your app


    const swStats = require('swagger-stats');
    const apiSpec = require('swagger.json');


    const swStats = require('swagger-stats');
    const apiSpec = require('swagger.json');
    const fastify = require('fastify')({
        logger: true
    fastify.register(swStats.getFastifyPlugin, {swaggerSpec:apiSpec});


    express-to-koa can be used which is just a simple Promise wrapper.

    const swStats = require('swagger-stats');
    const apiSpec = require('swagger.json');
    const e2k = require('express-to-koa');
    app.use(e2k(swStats.getMiddleware({ swaggerSpec:apiSpec })));


    const swStats = require('swagger-stats');
    const swaggerSpec = require('./petstore.json');
    const init = async () => {
        server = Hapi.server({
            port: 3040,
            host: 'localhost'
        await server.register({
            plugin: swStats.getHapiPlugin,
            options: {
        await server.start();
        console.log('Server running on %s', server.info.uri);


    const restify = require('restify');
    const swStats = require('swagger-stats');
    const apiSpec = require('swagger.json');
    const server = restify.createServer();

    See /examples for sample apps

    Get Statistics with API

    $ curl http://<your app host:port>/swagger-stats/stats
      "startts": 1501647865959,
      "all": {
        "requests": 7,
        "responses": 7,
        "errors": 3,
        "info": 0,
        "success": 3,
        "redirect": 1,
        "client_error": 2,
        "server_error": 1,
        "total_time": 510,
        "max_time": 502,
        "avg_time": 72.85714285714286,
        "total_req_clength": 0,
        "max_req_clength": 0,
        "avg_req_clength": 0,
        "total_res_clength": 692,
        "max_res_clength": 510,
        "avg_res_clength": 98,
        "req_rate": 1.0734549915657108,
        "err_rate": 0.4600521392424475
      "sys": {
        "rss": 59768832,
        "heapTotal": 36700160,
        "heapUsed": 20081776,
        "external": 5291923,
        "cpu": 0
      "name": "swagger-stats-testapp",
      "version": "0.90.1",
      "hostname": "hostname",
      "ip": ""

    Take a look at Documentation for more details on API and returned statistics.

    Get Prometheus Metrics

    $ curl http://<your app host:port>/swagger-stats/metrics
    # HELP api_all_request_total The total number of all API requests received
    # TYPE api_all_request_total counter
    api_all_request_total 88715
    # HELP api_all_success_total The total number of all API requests with success response
    # TYPE api_all_success_total counter
    api_all_success_total 49051
    # HELP api_all_errors_total The total number of all API requests with error response
    # TYPE api_all_errors_total counter
    api_all_errors_total 32152
    # HELP api_all_client_error_total The total number of all API requests with client error response
    # TYPE api_all_client_error_total counter
    api_all_client_error_total 22986
    . . . . . . . . . .  


    See Changelog

    Enhancements and Bug Reports

    If you find a bug, or have an enhancement in mind please post issues on GitHub.




    npm i swagger-stats-json-formatted

    DownloadsWeekly Downloads






    Unpacked Size

    8.88 MB

    Total Files


    Last publish


    • matrunchyk