{"id":21869714,"url":"https://github.com/cha87de/kvmtop","last_synced_at":"2025-10-24T21:05:04.311Z","repository":{"id":53720357,"uuid":"38934051","full_name":"cha87de/kvmtop","owner":"cha87de","description":"A monitoring tool for black box virtual machines from KVM hypervisor level","archived":false,"fork":false,"pushed_at":"2021-03-18T06:15:46.000Z","size":426,"stargazers_count":89,"open_issues_count":15,"forks_count":18,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-04-14T23:41:34.532Z","etag":null,"topics":["kvm","kvm-hypervisor","linux","monitoring","virtual-machine"],"latest_commit_sha":null,"homepage":"https://cha87de.github.io/kvmtop/","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cha87de.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}},"created_at":"2015-07-11T17:17:42.000Z","updated_at":"2025-02-13T20:01:13.000Z","dependencies_parsed_at":"2022-09-04T05:23:01.219Z","dependency_job_id":null,"html_url":"https://github.com/cha87de/kvmtop","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cha87de%2Fkvmtop","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cha87de%2Fkvmtop/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cha87de%2Fkvmtop/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cha87de%2Fkvmtop/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cha87de","download_url":"https://codeload.github.com/cha87de/kvmtop/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248981257,"owners_count":21193143,"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":["kvm","kvm-hypervisor","linux","monitoring","virtual-machine"],"created_at":"2024-11-28T06:08:58.957Z","updated_at":"2025-10-24T21:05:04.238Z","avatar_url":"https://github.com/cha87de.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Codacy Badge](https://api.codacy.com/project/badge/Grade/2111f329884b41efa85e4556311b1f1b)](https://app.codacy.com/app/cha87de/kvmtop?utm_source=github.com\u0026utm_medium=referral\u0026utm_content=cha87de/kvmtop\u0026utm_campaign=Badge_Grade_Dashboard)\n[![Build Status](https://travis-ci.org/cha87de/kvmtop.svg?branch=master)](https://travis-ci.org/cha87de/kvmtop)\n[![GitHub release](https://img.shields.io/github/release/cha87de/kvmtop.svg)](https://github.com/cha87de/kvmtop/releases)\n[![GitHub stars](https://img.shields.io/github/stars/cha87de/kvmtop.svg?style=social\u0026label=Stars)](https://github.com/cha87de/kvmtop)\n[![Go Report Card](https://goreportcard.com/badge/github.com/cha87de/kvmtop)](https://goreportcard.com/report/github.com/cha87de/kvmtop)\n[![GoDoc](https://godoc.org/github.com/cha87de/kvmtop?status.svg)](https://godoc.org/github.com/cha87de/kvmtop)\n[![Docker Pulls](https://img.shields.io/docker/pulls/cha87de/kvmtop.svg)](https://hub.docker.com/r/cha87de/kvmtop/)\n\n## What kvmtop does\nkvmtop reads utilisation metrics about virtual machines running on a KVM hypervisor from the Linux proc filesystem and from libvirt.\n\n*Why yet another monitoring tool for virtual machines?*\n\nKvmtop takes into account the difference between utilisation inside and\noutside the virtual machine, which differs in cases of overprovisioning. Kvmtop collects utilisation values of the hypervisor for virtual machines, to measure the overhead needed to run a virtual machine. Kvmtop will help to identify resource shortcomings, leading \nto the \"noisy neighbour\" effect.\n\nThe conceptual idea behind kvmtop is scientifically published and described in \"Reviewing Cloud Monitoring: Towards Cloud Resource Profiling.\"\n\n```\n@inproceedings{hauser2018reviewing,\n  title={Reviewing Cloud Monitoring: Towards Cloud Resource Profiling},\n  author={Hauser, Christopher B and Wesner, Stefan},\n  booktitle={2018 IEEE 11th International Conference on Cloud Computing (CLOUD)},\n  pages={678--685},\n  year={2018},\n  organization={IEEE}\n}\n```\n\n*What does kvmtop offer?*\n\nThe command line tool can be used by sysadmins, using a console ui. Text or JSON output further allows to process the monitoring data. A build in TCP output allows to send the data directly to a monitoring data sink, e.g. logstash.\n\n## Installation\n\nDownload and install the [latest version of the kvmtop\nbuild](https://github.com/cha87de/kvmtop/releases/latest). Available formats are the binary, Deb or Rpm packages, and a Docker image.\n\nOn Ubuntu, download the deb file and install it with `dpkg -i kvmtop_VERSION_linux_amd64.deb`. Similarly, on a rpm based system (e.g. Centos 7) with `rpm -Uvh kvmtop_VERSION_linux_amd64.rpm`.\n\n\n### Docker Usage\n\nTo use the Docker image, create a container from `cha87de/kvmtop:master` for the current master build or `cha87de/kvmtop:latest` to use the latest stable release. \n\n```\ndocker run --rm \\\n  -v /var/run/libvirt/libvirt-sock:/var/run/libvirt/libvirt-sock \\\n  --privileged --pid=\"host\" \\\n  cha87de/kvmtop:latest \\\n  /bin/kvmtop -c qemu:///system --printer text --cpu --mem\n```\n\nNotes for Docker: i) If libvirt is accessible via a local socket, a volume has to mount this socket inside the container. ii) Containers per design isolate the container in its own process namespace, which hinders reading from the proc filesystem. `--pid=\"host\"` softens this isolation, so kvmtop has access to the hosts proc files. iii) the `--privileged` is required for the IO Collector, which reads files only accessible as root user.\n\n## General Usage\n\n```\nUsage:\n  kvmtop [OPTIONS]\n\nMonitor virtual machine experience from outside on KVM hypervisor level\n\nApplication Options:\n  -v, --version        Show version\n  -f, --frequency=     Frequency (in seconds) for collecting metrics (default: 1)\n  -r, --runs=          Amount of collection runs (default: -1)\n  -c, --connection=    connection uri to libvirt daemon (default: qemu:///system)\n      --procfs=        path to the proc filesystem (default: /proc)\n      --verbose        Verbose output, adds more detailed fields\n      --cpu            enable cpu metrics\n      --mem            enable memory metrics\n      --disk           enable disk metrics\n      --net            enable network metrics\n      --io             enable io metrics (requires root)\n      --pressure       enable pressure metrics (requires kernel 4.20+)\n      --host           enable host metrics\n  -p, --printer=       the output printer to use (valid printers: ncurses, text, json) (default: ncurses)\n  -o, --output=        the output channel to send printer output (valid output: stdout, file, tcp, udp) (default: stdout)\n      --target=        for output 'file' the location, for 'tcp' or 'udp' the url (host:port) to the server\n      --netdev=        The network device used for the virtual traffic\n\nHelp Options:\n  -h, --help           Show this help message\n\n```\n\nExemplary output\n```\nUUID                                 name          cpu_cores cpu_total cpu_steal cpu_other_total cpu_other_steal\n0dbe2ae8-1ee4-4b43-bdf3-b533dfe75486 ubuntu14.04-2 2         53        0         5               1\n```\n\nPlease note: although the connection to libvirt may work remote (e.g. via ssh), kvmtop requires access to the /proc file system of the hypervisor's operating system. You can use the `--connection` to connect to a remote libvirt, but need to mount the remote proc fs and specify the location with `--procfs`.\n\n### Printers and Outputs\n\nPrinters define the representation of the monitoring data. This can be for humans in ncurses, or for further processing text (space separated) or json.\n\nOutputs define the location where the printers send data to. Output works for text and json printers, yet not for ncurses. The output may be a file or a remote tcp server.\n\nExample scenarios:\n\n```\n# write monitoring data to log file\nkvmtop --cpu --printer=text --output=file --target=/var/log/kvmtop.log\n\n# send mointoring data to tcp server (e.g. logstash with tcp input)\nkvmtop --cpu --printer=json --output=tcp --target=127.0.0.1:12345\n```\n\n## Collectors \u0026 Their Fields\n\n| Collector | cli option | description |\n| --- | --- | --- |\n| CPU Collector | --cpu | CPU Stats (host and VMs) like cores, utilisation, frequency|\n| Memory Collector | --mem | Memory stats (host and VMs)  like capacity, allocation, faults |\n| Disk Collector | --disk | Disk stats (host and VMs) like capacity, utilisation, reads/writes, etc. |\n| Network Collector | --net | Network stats (host and VMs) like transmitted and received bytes, packets, errors, etc. |\n| I/O Collector | --io | Disk I/O stats (host and VMs) like reads/writes |\n| PSI Collector | --psi | Pressure Stall Information (PSI) values (host only) |\n| Host | --host | Host details (host only) |\n\nA more detailed list, including all metrics is available here at [./docs/README.md](https://github.com/cha87de/kvmtop/blob/master/docs/README.md).\n\n## kvmtop with InfluxDB\n\nkvmtop can be used as a monitoring agent to send data to an InfluxDB instance: kvmtop transmits JSON data via TCP to logstash, while logstash writes to InfluxDB. More detailes are available at [https://github.com/cha87de/kvmtop-datasink/](https://github.com/cha87de/kvmtop-datasink/).\n\n```    \n                                      kvmtop-datasink\n                  +-----------------------------------------------------+\n                  |                                                     |\n+------------     | +------------+     +------------+     +-----------+ |\n|           |     | |            |     |            |     |           | |\n|  kvmtop   +---\u003e | |  logstash  +---\u003e |  influxdb  +---\u003e |  grafana  | |\n|           |     | |            |     |            |     |           | |\n+------------     | +------------+     +------------+     +-----------+ |\n                  |                                                     |\n                  +-----------------------------------------------------+\n```\n\n# Development Guide\n\nInstall the golang binary and the required dependencies libvirt-dev and libncurses5-dev packages. Create a new folder as your kvmtop workspace, e.g. /opt/kvmtop.  Then follow these steps:\n```\ncd /opt/kvmtop\nexport GOPATH=$(pwd) # take workspace as GOPATH\ngo get -d github.com/cha87de/kvmtop/...   # download all source files, including depencencies\ngo install github.com/cha87de/kvmtop/...  # compile kvmtop binaries\n```\nThe resulting binaries are then located in `/opt/kvmtop/bin`.\n\nFurther reading: https://golang.org/doc/code.html\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcha87de%2Fkvmtop","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcha87de%2Fkvmtop","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcha87de%2Fkvmtop/lists"}