{"id":50298907,"url":"https://github.com/aminalaee/vllm-doctor","last_synced_at":"2026-05-28T11:00:43.466Z","repository":{"id":358666119,"uuid":"1237548136","full_name":"aminalaee/vllm-doctor","owner":"aminalaee","description":"Diagnostic tool for vLLM inference servers","archived":false,"fork":false,"pushed_at":"2026-05-27T18:53:51.000Z","size":657,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-27T20:21:38.071Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://aminalaee.github.io/vllm-doctor/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aminalaee.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-13T09:31:39.000Z","updated_at":"2026-05-27T18:53:55.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/aminalaee/vllm-doctor","commit_stats":null,"previous_names":["aminalaee/vllm-doctor"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/aminalaee/vllm-doctor","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aminalaee%2Fvllm-doctor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aminalaee%2Fvllm-doctor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aminalaee%2Fvllm-doctor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aminalaee%2Fvllm-doctor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aminalaee","download_url":"https://codeload.github.com/aminalaee/vllm-doctor/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aminalaee%2Fvllm-doctor/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33605379,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-28T02:00:06.440Z","response_time":99,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":[],"created_at":"2026-05-28T11:00:24.661Z","updated_at":"2026-05-28T11:00:43.457Z","avatar_url":"https://github.com/aminalaee.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cimg src=\"https://raw.githubusercontent.com/aminalaee/vllm-doctor/main/docs/assets/wordmark.svg\" alt=\"vLLM Doctor\" width=\"360\"\u003e\n\n\u003cp\u003e\n\u003ca href=\"https://pypi.org/project/vllm-doctor/\"\u003e\n    \u003cimg src=\"https://badge.fury.io/py/vllm-doctor.svg\" alt=\"Package version\"\u003e\n\u003c/a\u003e\n\u003ca href=\"https://pypi.org/project/vllm-doctor/\"\u003e\n    \u003cimg src=\"https://img.shields.io/pypi/pyversions/vllm-doctor.svg?color=%2334D058\" alt=\"Supported Python versions\"\u003e\n\u003c/a\u003e\n\u003c/p\u003e\n\nDiagnose vLLM serving issues from `/metrics`.\n\n![vllm-doctor demo](https://raw.githubusercontent.com/aminalaee/vllm-doctor/main/docs/demo.png)\n\nvLLM Doctor reads production metrics and turns them into operational findings: what looks wrong, how confident the diagnosis is, and which vLLM knobs are worth checking first.\n\n```shell\nvllm-doctor --url http://localhost:8000/metrics\n```\n\n\u003e vLLM Doctor is not a dashboard replacement. It is a fast diagnostic snapshot for a single server or Prometheus target.\n\n## Why not just a dashboard?\n\nDashboards show metrics. vLLM Doctor explains inference-system behavior.\n\n|                          | Dashboards | vLLM Doctor |\n| ------------------------ | ---------- | ----------- |\n| Shows raw metrics        | ✓          | ✓           |\n| Explains what's wrong    | ✗          | ✓           |\n| Recommends vLLM configs  | ✗          | ✓           |\n| Requires setup           | ✓          | ✗           |\n| Works on a single server | ✗          | ✓           |\n\n## Installation\n\nWith pip:\n\n```shell\npip install vllm-doctor\n```\n\nWith uv:\n\n```shell\nuv tool install vllm-doctor\n```\n\n## Quickstart\n\nDirect scrape:\n\n```shell\nvllm-doctor --url http://localhost:8000/metrics\n```\n\nPrometheus:\n\n```shell\nvllm-doctor --url http://localhost:9090\n```\n\nOptions:\n\n```\nUsage: vllm-doctor [OPTIONS]\n\nOptions:\n  -u, --url      TEXT         URL to diagnose (vLLM /metrics or Prometheus).  [required]\n  -w, --window   TEXT         Time window (e.g. '1h', '30m', 'now').  [default: now]\n  -f, --format   [text|json]  Output format.  [default: text]\n  -v, --verbose               Show additional diagnostic detail.\n  -l, --live     INTEGER      Refresh interval in seconds (e.g. --live 10).\n  -c, --config   PATH         Path to config file (default: vllm-doctor.toml).\n      --help                  Show this message and exit.\n```\n\n## Example output\n\n```shell\n─────────── vLLM Doctor  ·  Health: CRITICAL  ·  Window: 5m ────────────\n\n╭─ ⚠ Queue pressure  [low confidence] ─────────────────────────────────╮\n│   Waiting requests: 7                                                │\n│                                                                      │\n│   → Add replicas or increase concurrency limits                      │\n│   → Inspect autoscaling thresholds                                   │\n╰──────────────────────────────────────────────────────────────────────╯\n╭─ ✖ KV cache pressure  [high confidence] ─────────────────────────────╮\n│   GPU KV cache usage: 94%  ·  Waiting requests: 7                    │\n│                                                                      │\n│   → Reduce max_num_seqs to limit concurrent sequences                │\n│   → Increase gpu_memory_utilization if GPU memory headroom exists    │\n╰──────────────────────────────────────────────────────────────────────╯\n\n  Queue Pressure       ⚠ warning     [low]\n  KV Cache Pressure    ✖ critical    [high]\n  Low Throughput       ✓ ok\n  Error Rate           ✓ ok\n  High TTFT            ✓ ok\n\n─────────────────────────── Observed Metrics ───────────────────────────\n\n  Requests Running                             12\n  Requests Waiting                              7\n  GPU Cache Usage        ███████████████████░ 94%\n  Generation Tokens/s                        42.0\n  TTFT p95 (s)                              3.200\n  TPOT p95 (s)                              0.050\n```\n\n## Documentation\n\nRead the full documentation: https://aminalaee.github.io/vllm-doctor\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faminalaee%2Fvllm-doctor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faminalaee%2Fvllm-doctor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faminalaee%2Fvllm-doctor/lists"}