{"id":18121269,"url":"https://github.com/ulissesf/qmassa","last_synced_at":"2025-03-30T06:30:28.002Z","repository":{"id":260215011,"uuid":"851925063","full_name":"ulissesf/qmassa","owner":"ulissesf","description":"Rust terminal-based tool for displaying GPUs usage stats on Linux.","archived":false,"fork":false,"pushed_at":"2025-03-23T19:28:35.000Z","size":10279,"stargazers_count":45,"open_issues_count":5,"forks_count":2,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-03-23T20:31:19.562Z","etag":null,"topics":["gpu","graphics","statistics","usage"],"latest_commit_sha":null,"homepage":"https://crates.io/crates/qmassa","language":"Rust","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/ulissesf.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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}},"created_at":"2024-09-03T23:25:20.000Z","updated_at":"2025-03-23T19:28:38.000Z","dependencies_parsed_at":"2024-12-08T07:18:20.137Z","dependency_job_id":"1eb3afb3-76de-4da2-99a2-81027520b234","html_url":"https://github.com/ulissesf/qmassa","commit_stats":null,"previous_names":["ulissesf/qmassa"],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ulissesf%2Fqmassa","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ulissesf%2Fqmassa/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ulissesf%2Fqmassa/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ulissesf%2Fqmassa/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ulissesf","download_url":"https://codeload.github.com/ulissesf/qmassa/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246285645,"owners_count":20752947,"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":["gpu","graphics","statistics","usage"],"created_at":"2024-11-01T06:00:46.597Z","updated_at":"2025-03-30T06:30:27.990Z","avatar_url":"https://github.com/ulissesf.png","language":"Rust","funding_links":[],"categories":["💻 Apps"],"sub_categories":["👨‍💻 System Administration"],"readme":"# qmassa!\n\n\u003cdiv align=\"center\"\u003e\n\n[![Crate Badge]][Crate]\n\n\u003c/div\u003e\n\n![qmassa](https://github.com/ulissesf/qmassa/blob/assets/assets/qmassa-v0.6.0.gif?raw=true)\n\n## General description\n\nqmassa is a Rust terminal-based tool for displaying GPUs usage stats on Linux.\nIt aims to display as much device and DRM clients (processes using the\nGPU) information as possible. Command-line options and which user is running\nthe tool control how much can be displayed.\n\nMost of the information is gathered through a GPU vendor and driver agnostic\ninterface such as standard files in /proc and /sys or by using udev. For some\nof the stats, though, a driver-specific way is needed, and qmassa then\nleverages what the kernel drivers expose in their uAPI (e.g. specific query\nioctls), specific sysfs files/directories or through perf events.\n\n## Requirements\n\nThe minimum requirements to compile \u0026 run qmassa are:\n\n* Compile-time: Rust v1.74 or later, pkg-config and libudev development packages\n* Runtime: Linux kernel v6.8 or later to report most usage stats\n\n## How to install it\n\nThe recommendation is to install qmassa using cargo. If you want to install\nthe latest release on crates.io using qmassa's lock file:\n\n```shell\ncargo install --locked qmassa\n```\n\nIf you want to install the latest development version using qmassa's lock file:\n\n```shell\ncargo install --locked --git https://github.com/ulissesf/qmassa\n```\n\n## How to use it\n\n\u003e [!IMPORTANT]\n\u003e If you want to run qmassa as a non-root user, it needs to be added to at\n\u003e least the video, render, and power groups (or equivalent ones in your Linux\n\u003e distribution). That is needed so qmassa can open the DRM device nodes to\n\u003e collect information from ioctls. If your user is not in the right groups\n\u003e you'll likely get \"Permission denied\" errors.\n\nRunning it as non-root user without any command-line options will display\nlimited device usage information and the DRM clients stats from processes that\nuser has access to in /proc.\n\n```shell\nqmassa\n```\n\nRunning it as the root user without any command-line options will display\nall the device avaiable stats along with all active DRM clients in the system.\n\n```shell\nsudo qmassa\n```\n\nOnly show a specific GPU device and DRM clients using it. The GPU device\nis specified by its PCI device slot name.\n\n```shell\nsudo qmassa -d 0000:03:00.0\n```\n\nOnly show DRM clients from the process tree starting at a specific PID.\n\n```shell\nsudo qmassa -p 2876\n```\n\nRunning for only 5 iterations (stats updates).\n\n```shell\nsudo qmassa -n 5\n```\n\nChanging the interval between stats updates to 1s (1000 ms). The UI will be\nupdated on the same frequency or whenever user interaction happens.\n\n```shell\nsudo qmassa -m 1000\n```\n\nShowing all DRM clients including the inactive ones (no memory allocated or\nengines being used).\n\n```shell\nsudo qmassa -a\n```\n\nRun qmassa's TUI and save stats to a JSON file.\n\n```shell\nsudo qmassa -t data.json\n```\n\nRun qmassa without the TUI and save stats to a JSON file.\n\n```shell\nsudo qmassa -x -t data.json\n```\n\nRun qmassa's TUI to replay data from a JSON file.\n\n```shell\nsudo qmassa replay -j data.json\n```\n\nPlot SVG charts (with \"chart\" prefix) for all GPUs data in a JSON file. Some\nexamples of generated charts can be seen below.\n\n```shell\nsudo qmassa plot -j data.json -o chart\n```\n\n\u003cimg src=\"https://github.com/ulissesf/qmassa/blob/assets/assets/chart-0000:03:00.0-engines.svg\" class=\"galleryItem\" width=200px\u003e\u003c/img\u003e\n\u003cimg src=\"https://github.com/ulissesf/qmassa/blob/assets/assets/chart-0000:03:00.0-freqs-gt0.svg\" class=\"galleryItem\" width=200px\u003e\u003c/img\u003e\n\u003cimg src=\"https://github.com/ulissesf/qmassa/blob/assets/assets/chart-0000:03:00.0-power.svg\" class=\"galleryItem\" width=200px\u003e\u003c/img\u003e\n\u003cimg src=\"https://github.com/ulissesf/qmassa/blob/assets/assets/chart-0000:03:00.0-meminfo.svg\" class=\"galleryItem\" width=200px\u003e\u003c/img\u003e\n\n## Fields description\n\n### Per device (on main screen)\n\n| Field        | Description                                    |\n| ------------ | ---------------------------------------------- |\n| DRIVER       | Kernel driver being used                       |\n| TYPE         | Integrated, Discrete or Unknown                |\n| DEVICE NODES | Character device nodes in /dev/dri             |\n| SMEM         | System memory used / Total system memory       |\n| VRAM         | Device memory used / Total device memory       |\n| [Engines]    | Overall engine usage in the last iteration     |\n| FRQ-*        | Actual frequency / Maximum frequency limit     |\n| POWER        | GPU power usage / Package power usage          |\n| TP-*         | Temperature                                    |\n| FAN-*        | Fan speed                                      |\n\nThe memory usage values are either in bytes (no letter), or in KiB\n(using \"K\" letter), or in MiB (using \"M\" letter), or in GiB (using \"G\"\nletter). The values are rounded to be easily displayed in a small space,\nbut if you save the stats to a JSON file you can get them all in bytes.\nVRAM data is only displayed for discrete GPUs.\n\nThe overall engines usage depends on the DRM clients that the user has\naccess to. In order to have a system view, please run qmassa as root.\n\nThe frequency graphs range from min to max values and plot the instant\ndriver-requested (if supported) and actual device/engines frequency for\neach iteration. The graph legend shows the latest value for those\nfrequencies. The graph also indicates the overall status and PL1\nthrottle reason (for now only valid on i915 and Xe drivers). All the\nfrequency values are in MHz.\n\nThe intention of the power reporting is to have values that are the\nclosest possible to the power usage from both the GPU and the larger package\n(or card) containing it. It's good to remember that larger package is\ndifferent on integrated vs discrete GPUs, and there are limitations on what\ndrivers expose and what they have visibility on so expect the information\nto vary a lot across GPUs and vendors. All the power usage values are in\nwatts (W).\n\nTemperatures and fan speeds are displayed only for discrete GPUs exposing\nthem through the hwmon kernel infrastructure (Intel and AMD, for now). The\ntemperature values are all in Celsius (C), and the fan speeds are all in\nrevolutions per minute (RPM).\n\n#### Driver support\n\nThe table below shows the current drivers and features supported in qmassa\nto get device information.\n\n| Driver | Dev Type | Mem Info | Engines | Freqs   | Power   | Client Mem Info | Temperatures | Fans |\n| ------ | :------: | :------: | :-----: | :-----: | :-----: | :-------------: | :----------: | :--: |\n| xe     | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: (only dGPUs, Linux kernel 6.15+) | :white_check_mark: (only dGPUs, Linux kernel 6.15+) |\n| i915   | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: (only dGPUs) | :white_check_mark: (only dGPUs) |\n| amdgpu | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: (only dGPUs) | :white_check_mark: (Linux kernel 6.13+) | :white_check_mark: (only dGPUs) | :white_check_mark: (only dGPUs) |\n| *      |  |  | :white_check_mark: (via DRM fdinfo) |  |  | :white_check_mark: (only \"memory\" region in DRM fdinfo) |  |  |\n\nqmassa is tested on some Intel and AMD GPUs but it relies heavily on kernel\ndrivers exposing consistent support across GPUs. If you have a problem,\nplease file an issue so we can debug it.\n\n#### Limitations\n\n* i915: the kernel driver doesn't track/report system memory used.\n* amdgpu: processes using kfd don't report engines and memory usage through\nany open file descriptor of a DRM device node.\n\n### Per DRM client (on main screen)\n\nDRM clients have unique IDs per device which are assigned for every open\nfile descriptor of one of the device nodes in the /dev/dri folder. The\nsame process ID (PID) can have multiple DRM clients and those file\ndescriptors can also be shared across different processes. qmassa shows\nonly one PID for every DRM client ID, but it can display multiple entries\nin the list with the same PID.\n\nThe engines and memory usage stats per DRM client are gathered following\nthe specs defined on\n\u003ca href=\"https://dri.freedesktop.org/docs/drm/gpu/drm-usage-stats.html\"\u003eDRM client usage stats\u003c/a\u003e.\n\n| Field        | Description                                     |\n| ------------ | ----------------------------------------------- |\n| PID          | Process ID                                      |\n| SMEM         | Resident amount of system memory                |\n| VRAM         | Resident amount of device memory                |\n| MIN          | Minor number of /dev/dri device node being used |\n| ID           | DRM client ID                                   |\n| [Engines]    | Engine usage in the last iteration              |\n| CPU          | CPU usage in the last iteration                 |\n| COMMAND      | [/proc/PID/comm] /proc/PID/cmdline              |\n\nThe memory usage for DRM clients follow the same format and units as\ndescribed in the previous per device section. All the values can also\nbe found in bytes when stats are saved to a JSON file. VRAM data is only\ndisplayed for DRM clients on discrete GPUs.\n\nThe engines reported are driver and vendor specific, and are read directly\nfrom the DRM fdinfo files in /proc.\n\nThe CPU usage is measured by how much CPU time that process used versus the\navailable time for that iteration. The percentage value is relative to\na single CPU, so in the case of processes with multiple threads the\ncalculated value can be higher than 100%.\n\n#### DRM client screen\n\nThe DRM client list can be scrolled up, down, left and right to select a row\nor to show long command lines. Selecting a row in the list (pressing Enter)\nopens a screen with just that DRM client stats and charts. In this screen,\nthe memory stats in the table provide some more information (see description\nbelow), while the other data is the same as on the main screen.\n\n| Field  | Description                                 |\n| ------ | ------------------------------------------- |\n| SMEM   | System memory resident / System memory used |\n| VRAM   | Device memory resident / Device memory used |\n\nThe VRAM data is only displayed for DRM clients on discrete GPUs.\n\n## Acknowledgements\n\nqmassa uses \u003ca href=\"https://ratatui.rs/\"\u003eRatatui\u003c/a\u003e for displaying a nice\nterminal-based UI and leverages [many](Cargo.toml) other Rust crates.\n\n## License\n\nCopyright © 2024-2025 Ulisses Furquim\n\nThis project is distributed under the terms of the Apache License (Version 2.0).\nSee [LICENSE](LICENSE) for details.\n\n\n[Crate Badge]: https://img.shields.io/crates/v/qmassa?logo=rust\u0026style=flat-square\u0026logoColor=E05D44\u0026color=E05D44\n[Crate]: https://crates.io/crates/qmassa\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fulissesf%2Fqmassa","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fulissesf%2Fqmassa","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fulissesf%2Fqmassa/lists"}