{"id":28578284,"url":"https://github.com/digitalocean/vmtop","last_synced_at":"2025-06-30T06:34:57.840Z","repository":{"id":48679389,"uuid":"248065213","full_name":"digitalocean/vmtop","owner":"digitalocean","description":"Real-time monitoring of KVM/Qemu VMs","archived":false,"fork":false,"pushed_at":"2024-04-20T04:48:36.000Z","size":168,"stargazers_count":66,"open_issues_count":8,"forks_count":21,"subscribers_count":10,"default_branch":"master","last_synced_at":"2025-06-11T01:09:28.110Z","etag":null,"topics":["bcc","ebpf","kvm","monitoring","performance","prometheus","qemu","virtualization"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/digitalocean.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"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,"zenodo":null}},"created_at":"2020-03-17T20:18:54.000Z","updated_at":"2025-05-14T19:35:12.000Z","dependencies_parsed_at":"2024-04-20T05:29:45.353Z","dependency_job_id":"d07777ea-59fb-42d1-aaa7-2e72c257bbc0","html_url":"https://github.com/digitalocean/vmtop","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/digitalocean/vmtop","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/digitalocean%2Fvmtop","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/digitalocean%2Fvmtop/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/digitalocean%2Fvmtop/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/digitalocean%2Fvmtop/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/digitalocean","download_url":"https://codeload.github.com/digitalocean/vmtop/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/digitalocean%2Fvmtop/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262724478,"owners_count":23354255,"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":["bcc","ebpf","kvm","monitoring","performance","prometheus","qemu","virtualization"],"created_at":"2025-06-11T01:09:24.938Z","updated_at":"2025-06-30T06:34:57.814Z","avatar_url":"https://github.com/digitalocean.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# vmtop\n\nMonitor various metrics for KVM/qemu guests and output in a top-like fashion.\nAlso aggregate the usage/allocation metrics at the NUMA node and host-level.\n\n## Main features\n\nIt can output as text on the console and write CSV files. The `graph-vmtop.py`\nscript generates graphs from those CSV files (record with `--csv \u003cdir\u003e`).\n\nThis script can also be ran with a Prometheus exporter enabled, like so:\n```\nsudo ./vmtop.py --prometheus [host:port]\n```\n\nThe host and port are optional, and will default to localhost:8000 if not\nspecified. \n\n## Example output\nExample output for the top 10 VMs experiencing the most vcpu steal per node:\n\n```\n$ sudo ./vmtop.py --vm --limit 10 --sort vcpu_steal\n[...]\nNode 0:\nName     PID     vcpu util   vcpu steal  vhost util  vhost steal emu util  emu steal disk read    disk write   rx           tx\nGuest01  48642   141.73 %    32.86 %     0.30 %      0.06 %      0.57 %    0.48 %    0.00 MB/s    0.00 MB/s    0.00 MB/s    0.00 MB/s\nGuest02  16830   219.07 %    29.74 %     28.45 %     22.13 %     0.54 %    1.30 %    0.00 MB/s    0.01 MB/s    2.49 MB/s    2.43 MB/s\nGuest03  17152   119.61 %    27.87 %     13.89 %     16.31 %     0.48 %    0.12 %    0.00 MB/s    0.00 MB/s    1.45 MB/s    1.39 MB/s\nGuest04  60782   52.90 %     16.70 %     0.79 %      0.75 %      0.61 %    0.19 %    0.00 MB/s    0.01 MB/s    0.02 MB/s    0.03 MB/s\nGuest05  33077   46.47 %     12.69 %     2.02 %      1.82 %      3.11 %    0.97 %    0.00 MB/s    2.06 MB/s    0.24 MB/s    0.14 MB/s\nGuest06  39435   41.70 %     10.01 %     17.36 %     12.85 %     0.98 %    0.08 %    0.00 MB/s    0.00 MB/s    0.27 MB/s    0.30 MB/s\nGuest07  5196    26.49 %     9.28 %      0.03 %      0.00 %      0.51 %    0.09 %    0.00 MB/s    0.00 MB/s    0.00 MB/s    0.00 MB/s\nGuest08  56822   55.63 %     8.77 %      9.33 %      5.61 %      0.53 %    0.17 %    0.00 MB/s    0.00 MB/s    0.30 MB/s    0.30 MB/s\nGuest09  65751   36.59 %     8.54 %      6.26 %      3.42 %      0.76 %    0.06 %    0.08 MB/s    0.04 MB/s    0.18 MB/s    0.18 MB/s\nGuest10  25320   26.61 %     8.44 %      0.06 %      0.00 %      5.30 %    2.72 %    0.00 MB/s    0.06 MB/s    0.00 MB/s    0.00 MB/s\n  Node 0: vcpu util: 80.85%, vcpu steal: 6.49%, emulators util: 1.71%, emulators steal: 0.89%\n  Node 0: 79 VMs (168 vcpus, 306.00 GB mem allocated, 231.98 GB mem used)\nNode 1:\nName     PID     vcpu util   vcpu steal  vhost util  vhost steal emu util  emu steal disk read    disk write   rx           tx\nGuest11  14506   29.49 %     0.70 %      0.00 %      0.00 %      0.45 %    0.01 %    0.00 MB/s    0.01 MB/s    0.00 MB/s    0.00 MB/s\nGuest12  52580   28.69 %     0.63 %      4.55 %      0.26 %      0.60 %    0.08 %    0.12 MB/s    0.00 MB/s    0.16 MB/s    0.15 MB/s\nGuest13  60864   36.45 %     0.56 %      0.06 %      0.00 %      4.25 %    0.06 %    0.00 MB/s    0.03 MB/s    0.00 MB/s    0.00 MB/s\nGuest14  69426   64.98 %     0.54 %      11.06 %     0.79 %      0.09 %    0.00 %    0.00 MB/s    0.02 MB/s    4.20 MB/s    3.87 MB/s\nGuest15  52138   52.45 %     0.39 %      10.66 %     0.64 %      0.75 %    0.02 %    0.22 MB/s    0.00 MB/s    0.43 MB/s    0.38 MB/s\nGuest16  38308   57.05 %     0.25 %      12.03 %     0.93 %      1.18 %    0.03 %    0.51 MB/s    0.00 MB/s    0.47 MB/s    0.56 MB/s\nGuest17  7700    11.87 %     0.25 %      0.08 %      0.00 %      4.16 %    0.05 %    0.00 MB/s    0.03 MB/s    0.00 MB/s    0.00 MB/s\nGuest18  39542   39.46 %     0.24 %      7.61 %      0.51 %      0.77 %    0.02 %    0.16 MB/s    0.00 MB/s    0.27 MB/s    0.27 MB/s\nGuest19  1381    49.03 %     0.24 %      9.01 %      0.72 %      0.76 %    0.05 %    0.25 MB/s    0.00 MB/s    0.35 MB/s    0.43 MB/s\nGuest20  6945    36.15 %     0.24 %      6.42 %      0.45 %      0.77 %    0.04 %    0.21 MB/s    0.00 MB/s    0.23 MB/s    0.36 MB/s\n  Node 1: vcpu util: 41.88%, vcpu steal: 0.20%, emulators util: 1.87%, emulators steal: 0.08%\n  Node 1: 131 VMs (161 vcpus, 210.00 GB mem allocated, 193.42 GB mem used)\n```\n\n# Dependencies\n\nThe tool currently depends on `numastat` being in the `$PATH`.\n\nBesides that dependency, one design rule of this tool is that it should be easy\nto just download it and run without any additional setup. We use very common\nPython modules and the advanced features such as Prometheus and eBPF are\noptional.\n\nThis tool has been mostly tested on Ubuntu Bionic 18.04, but should be easy to\nrun on other platforms.\n\nThe optional dependencies are:\n* `python3-daemon` for the the `--daemon` option\n* `python3-bcc` for the `--vmexit` option\n* `python3-prometheus-client` for the `--prometheus` option\n\n## Assumptions\n\nThe node-level information assumes a VM mostly runs where most of its memory is\nallocated, if a VM can float between NUMA nodes, the node-level information may\nnot be accurate (and a warning will be shown). The VM-level data is accurate\nregardless of the pinning.\n\n## Feedback\n\nThis tool is a quick script to solve the issue of live monitoring resource\nallocation and usage by VMs. We plan to keep improving it over time. \n\n\n## Extras\n\nIn the `extras` folder, there are other ad-hoc tools for monitoring various\nperformance aspects of KVM.  The tools are in various states of maintenance,\nfeel free to reach out if you have questions or suggestions for improvements.\nThe features from those scripts may end up in vmtop at some point, but for now\nthey are tested outside.\n\n### guesttime.bt\n\n`bpftrace` tool to check statistically how long a vCPU spends inside the guest\nwhen it is scheduled in.\n\n\n### Core-scheduling and KVM\n\nThe `core-sched-stats.py` script ensures that the core scheduling\nfeature works properly and accounts for the time spent by a vCPU in various\nscheduling modes (co-scheduled with idle, with a compatible task, or a foreign\ntask).\n\nThis script works with perf trace recorded:\n```\nsudo perf record -e kvm:kvm_entry -e kvm:kvm_exit -e sched:sched_switch -e sched:sched_waking -o perf.data -a sleep 60\n```\n\nand can be converted to CTF like so (requires perf compiled with CTF support):\n```\nperf data convert --to-ctf=./ctf -i perf.data\n```\n\nIf you see this message and the number of chunks is greater than 1 or 2, consider writing your `perf.data` to a ramdisk instead\nof your local disk:\n```\nProcessed 7378132 events and lost 1 chunks!\nCheck IO/CPU overload!\n```\n\nIt depends on Babeltrace compiled with the python library and Perf compiled with the CTF support. On bionic:\n\n```\napt-get install libbabeltrace-dev libbabeltrace-ctf-dev python3-babeltrace babeltrace\n```\n\nThen rebuild `perf` so it will detect the new library.\n\nIn order to run `kvm_co_sched_stats.py`, the siblings list must be provided in a text file with the `--topology` flag.\nTo collect this data, run this on the target HV:\n```\nfor i in /sys/devices/system/cpu/cpu*/topology/thread_siblings_list; do cat $i; done \u003e out.txt\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdigitalocean%2Fvmtop","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdigitalocean%2Fvmtop","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdigitalocean%2Fvmtop/lists"}