{"id":13453941,"url":"https://github.com/slanatech/swagger-stats","last_synced_at":"2025-05-14T20:10:06.275Z","repository":{"id":21109567,"uuid":"83271262","full_name":"slanatech/swagger-stats","owner":"slanatech","description":"API Observability. Trace API calls and Monitor API performance, health and usage statistics in Node.js Microservices.","archived":false,"fork":false,"pushed_at":"2024-04-22T07:54:50.000Z","size":41081,"stargazers_count":918,"open_issues_count":72,"forks_count":141,"subscribers_count":20,"default_branch":"master","last_synced_at":"2025-05-14T02:23:34.708Z","etag":null,"topics":["api","api-telemetry","collects-statistics","devops","exposes-statistics","grafana","kibana","metrics","microservices","monitoring","nodejs","observability","performance","prometheus","rest","statistics","swagger","swagger-stats"],"latest_commit_sha":null,"homepage":"https://swaggerstats.io/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/slanatech.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"sv2"}},"created_at":"2017-02-27T05:23:26.000Z","updated_at":"2025-05-10T09:17:38.000Z","dependencies_parsed_at":"2023-01-16T22:00:50.895Z","dependency_job_id":"ad2b1ce8-8049-44a5-bd3f-a069b5379f02","html_url":"https://github.com/slanatech/swagger-stats","commit_stats":{"total_commits":419,"total_committers":29,"mean_commits":"14.448275862068966","dds":"0.12410501193317425","last_synced_commit":"6370130440c429e4940f71c9d2bf4a70a7193227"},"previous_names":[],"tags_count":37,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/slanatech%2Fswagger-stats","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/slanatech%2Fswagger-stats/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/slanatech%2Fswagger-stats/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/slanatech%2Fswagger-stats/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/slanatech","download_url":"https://codeload.github.com/slanatech/swagger-stats/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254101270,"owners_count":22014898,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","api-telemetry","collects-statistics","devops","exposes-statistics","grafana","kibana","metrics","microservices","monitoring","nodejs","observability","performance","prometheus","rest","statistics","swagger","swagger-stats"],"created_at":"2024-07-31T08:00:49.557Z","updated_at":"2025-05-14T20:10:01.263Z","avatar_url":"https://github.com/slanatech.png","language":"JavaScript","readme":"\u003cp align=\"center\"\u003e\n\u003cimg src=\"https://github.com/slanatech/swagger-stats/blob/master/screenshots/logo.png?raw=true\" alt=\"swagger-stats\"/\u003e\n\u003c/p\u003e\n\n# swagger-stats | API Observability\n\n\n####  [https://swaggerstats.io](https://swaggerstats.io) | [Guide](https://swaggerstats.io/guide/) \n\n[![CircleCI](https://dl.circleci.com/status-badge/img/gh/slanatech/swagger-stats/tree/master.svg?style=svg)](https://dl.circleci.com/status-badge/redirect/gh/slanatech/swagger-stats/tree/master)\n[![Coverage Status](https://coveralls.io/repos/github/slanatech/swagger-stats/badge.svg?branch=master\u0026dummy)](https://coveralls.io/github/slanatech/swagger-stats?branch=master\u0026dummy)\n[![npm version](https://badge.fury.io/js/swagger-stats.svg)](https://badge.fury.io/js/swagger-stats)\n[![npm downloads](https://img.shields.io/npm/dm/swagger-stats.svg)](https://img.shields.io/npm/dm/swagger-stats)\n[![Gitter](https://badges.gitter.im/swagger-stats/community.svg)](https://gitter.im/swagger-stats/community?utm_source=badge\u0026utm_medium=badge\u0026utm_campaign=pr-badge)\n\n\n#### Trace API calls and Monitor API performance, health and usage statistics in Node.js Microservices\n\n### Express, Fastify, Koa, Hapi, Restify\n\n**swagger-stats** traces REST API requests and responses in Node.js Microservices, and collects statistics per API Operation.\n**swagger-stats** detects API operations based on express routes. You may also provide [Swagger (Open API) specification](https://swagger.io/specification/), \nand swagger-stats will match API requests with API Operations defined in swagger specification. \n\n**swagger-stats** exposes statistics and metrics per API Operation, such as `GET /myapi/:parameter`, or `GET /pet/{petId}`\n \n\n### Built-In API Telemetry \n\n\u003e **swagger-stats** provides built-in Telemetry UX, so you may enable **swagger-stats** in your app, and start monitoring immediately, with no infrastructure requirements.\n\u003e Navigate to `http://\u003cyour app host:port\u003e/swagger-stats/`   \n\n\n![swagger-stats Built-In Telemetry](screenshots/swsux.gif?raw=true)\n\n\n       \n### API Analytics with [Elasticsearch](https://www.elastic.co/) and [Kibana](https://www.elastic.co/products/kibana)\n\n\u003e **swagger-stats** stores details about each request/response in [Elasticsearch](https://www.elastic.co/), so you may use [Kibana](https://www.elastic.co/products/kibana) \n\u003e to perform detailed analysis of API usage over time, build visualizations and dashboards\n\n\n![swagger-stats Kibana Dashboard](screenshots/kibana.gif?raw=true)\n\nSee `dashboards/elastic6` for swagger-stats Kibana visualizations and dashboards\n \n\n### Monitoring and Alerting with [Prometheus](https://prometheus.io/) and [Grafana](https://grafana.com/)\n\n\u003e **swagger-stats** exposes metrics in [Prometheus](https://prometheus.io/) format, so you may use [Prometheus](https://prometheus.io/) and [Grafana](https://grafana.com/) to setup API monitoring and alerting\n\n\n![swagger-stats Prometheus Dashboard](screenshots/prometheus-dashboard-2-sm.png?raw=true)\n\n\nSee `dashboards/prometheus` for swagger-stats Grafana dashboards \n\n\n\nWith statistics and metrics exposed by **swagger-stats** you may spot problematic API endpoints, see where most of errors happens, \ncatch long-running requests, analyze details of last errors, observe trends, setup alerting. \n\n \n**swagger-stats** provides:\n* Metrics in [Prometheus](https://prometheus.io/) format, so you may use [Prometheus](https://prometheus.io/) and [Grafana](https://grafana.com/) to setup API monitoring and alerting\n* Storing details about each API Request/Response in [Elasticsearch](https://www.elastic.co/), so you may use [Kibana](https://www.elastic.co/products/kibana) to perform analysis of API usage over time, build visualizations and dashboards  \n* Built-in API Telemetry UI, so you may enable swagger-stats in your app, and start monitoring right away, with no additional tools required\n* Exposing collected statistics via API, including:\n* Counts of requests and responses(total and by response class), processing time (total/avg/max), \ncontent length(total/avg/max) for requests and responses, rates for requests and errors. \nThis is baseline set of stats. \n* Statistics by Request Method: baseline stats collected for each request method\n* Timeline: baseline stats collected for each 1 minute interval during last 60 minutes. Timeline helps you to analyze trends.\n* Errors: count of responses per each error code, top \"not found\" resources, top \"server error\" resources\n* Last errors: request and response details for the last 100 errors (last 100 error responses)\n* Longest requests: request and response details for top 100 requests that took longest time to process (time to send response)\n* Tracing: Request and Response details - method, URLs, parameters, request and response headers, addresses, start/stop times and processing duration, matched API Operation info\n* 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](https://swagger.io/specification/) \n* CPU and Memory Usage of Node process\n\n\n## How to Use \n\n\n### Install \n\n```\nnpm install swagger-stats --save\n```\n\nIf you haven't added prom-client already, you should do this now. It's a [peer dependency](https://nodejs.org/en/blog/npm/peer-dependencies) of swagger-stats as of version [0.95.19](https://github.com/slanatech/swagger-stats/releases/tag/v0.95.19).\n\n```\nnpm install prom-client@12 --save\n```\n\n### Enable swagger-stats middleware in your app\n\n#### Express\n\n```javascript\nconst swStats = require('swagger-stats');\nconst apiSpec = require('swagger.json');\napp.use(swStats.getMiddleware({swaggerSpec:apiSpec}));\n```\n\n#### Fastify\n\n```javascript\nconst swStats = require('swagger-stats');\nconst apiSpec = require('swagger.json');\n\nconst fastify = require('fastify')({\n    logger: true\n});\n\n// Enable swagger-stats\nfastify.register(require('fastify-express')).then(()=\u003e{\n    fastify.register(swStats.getFastifyPlugin, {swaggerSpec:apiSpec});\n});\n\n```\n\n\n#### Koa\n\n[`express-to-koa`](https://github.com/kaelzhang/express-to-koa) can be used which is just a simple `Promise` wrapper.\n\n```javascript\nconst swStats = require('swagger-stats');\nconst apiSpec = require('swagger.json');\nconst e2k = require('express-to-koa');\napp.use(e2k(swStats.getMiddleware({ swaggerSpec:apiSpec })));\n```\n\n#### Hapi\n\n```javascript\nconst swStats = require('swagger-stats');\nconst swaggerSpec = require('./petstore.json');\n\nconst init = async () =\u003e {\n\n    server = Hapi.server({\n        port: 3040,\n        host: 'localhost'\n    });\n\n    await server.register({\n        plugin: swStats.getHapiPlugin,\n        options: {\n             swaggerSpec:swaggerSpec\n        }\n    });\n\n    await server.start();\n    console.log('Server running on %s', server.info.uri);\n};\n````\n\n#### Restify\n\n```javascript\nconst restify = require('restify');\nconst swStats = require('swagger-stats');\nconst apiSpec = require('swagger.json');\n\nconst server = restify.createServer();\n\nserver.pre(swStats.getMiddleware({\n    swaggerSpec:apiSpec,\n}));\n```\n\nSee `/examples` for sample apps\n\n### Get Statistics with API\n\n\n```\n$ curl http://\u003cyour app host:port\u003e/swagger-stats/stats\n{\n  \"startts\": 1501647865959,\n  \"all\": {\n    \"requests\": 7,\n    \"responses\": 7,\n    \"errors\": 3,\n    \"info\": 0,\n    \"success\": 3,\n    \"redirect\": 1,\n    \"client_error\": 2,\n    \"server_error\": 1,\n    \"total_time\": 510,\n    \"max_time\": 502,\n    \"avg_time\": 72.85714285714286,\n    \"total_req_clength\": 0,\n    \"max_req_clength\": 0,\n    \"avg_req_clength\": 0,\n    \"total_res_clength\": 692,\n    \"max_res_clength\": 510,\n    \"avg_res_clength\": 98,\n    \"req_rate\": 1.0734549915657108,\n    \"err_rate\": 0.4600521392424475\n  },\n  \"sys\": {\n    \"rss\": 59768832,\n    \"heapTotal\": 36700160,\n    \"heapUsed\": 20081776,\n    \"external\": 5291923,\n    \"cpu\": 0\n  },\n  \"name\": \"swagger-stats-testapp\",\n  \"version\": \"0.90.1\",\n  \"hostname\": \"hostname\",\n  \"ip\": \"127.0.0.1\"\n}\n```\n\nTake a look at [Documentation](https://swaggerstats.io/guide/) for more details on API and returned statistics.\n\n\n### Get Prometheus Metrics \n\n\n```\n$ curl http://\u003cyour app host:port\u003e/swagger-stats/metrics\n# HELP api_all_request_total The total number of all API requests received\n# TYPE api_all_request_total counter\napi_all_request_total 88715\n# HELP api_all_success_total The total number of all API requests with success response\n# TYPE api_all_success_total counter\napi_all_success_total 49051\n# HELP api_all_errors_total The total number of all API requests with error response\n# TYPE api_all_errors_total counter\napi_all_errors_total 32152\n# HELP api_all_client_error_total The total number of all API requests with client error response\n# TYPE api_all_client_error_total counter\napi_all_client_error_total 22986\n\n. . . . . . . . . .  \n\n```\n\n#### Default Metrics\n\n\nTo collect [prom-client default metrics](https://github.com/siimon/prom-client#default-metrics):\n\n```javascript\nconst swaggerStats = require('swagger-stats');\nconst promClient = require('prom-client');\n\npromClient.collectDefaultMetrics();\n```\n\nSome Node.js specific metrics are included, such as event loop lag:\n\n```\n# HELP nodejs_eventloop_lag_seconds Lag of event loop in seconds.\n# TYPE nodejs_eventloop_lag_seconds gauge\nnodejs_eventloop_lag_seconds 0.000193641 1597303877464\n\n. . . . . . . . . .  \n\n```\n\n\n## Updates \n\nSee [Changelog](https://github.com/slanatech/swagger-stats/blob/master/CHANGELOG.md)\n\n## Enhancements and Bug Reports\n\nIf you find a bug, or have an enhancement in mind please post [issues](https://github.com/slanatech/swagger-stats/issues) on GitHub.\n\n## License\n \nMIT\n","funding_links":["https://github.com/sponsors/sv2"],"categories":["Packages","JavaScript","Repository","包","目录","Middleware"],"sub_categories":["Debugging / Profiling","Application Performance Monitoring (APM)","调试 / 分析","调试/分析","调试"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fslanatech%2Fswagger-stats","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fslanatech%2Fswagger-stats","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fslanatech%2Fswagger-stats/lists"}