qmassa!

General description

qmassa is a Rust terminal-based tool for displaying GPUs usage stats on Linux. It aims to display as much device and DRM clients (processes using the GPU) information as possible. Command-line options and which user is running the tool control how much can be displayed.

Most of the information is gathered through a GPU vendor and driver agnostic interface such as standard files in /proc and /sys or by using udev. For some of the stats, though, a driver-specific way is needed, and qmassa then leverages what the kernel drivers expose in their uAPI (e.g. specific query ioctls), specific sysfs files/directories or through perf events.

How to install it

The recommendation is to install qmassa using cargo. If you want to install the latest release on crates.io and using qmassa's lock file:

cargo install --locked qmassa

If you want to install the latest development version using qmassa's lock file:

cargo install --locked --git https://github.com/ulissesf/qmassa

How to use it

[!IMPORTANT] If you want to run qmassa as a non-root user, it needs to be added to at least the video, render, and power groups (or equivalent ones in your Linux distribution). That is needed so qmassa can open the DRM device nodes to collect information from ioctls. If your user is not in the right groups you'll likely get "Permission denied" errors.

Running it as non-root user and wihout any command-line options will display limited device usage information and the DRM clients stats from processes that user has access to in /proc.

qmassa

Running it as the root user and wihout any commnad-line options will display all the device avaiable stats along with all active DRM clients in the system.

sudo qmassa

Only show a specific GPU device and DRM clients using it. The GPU device is specified by its PCI device slot name.

sudo qmassa -d 0000:03:00.0

Only show DRM clients from the process tree starting at a specific PID.

sudo qmassa -p 2876

Running for only 5 iterations (stats updates).

sudo qmassa -n 5

Changing the interval between stats updates to 1s (1000 ms). The UI will be updated on the same frequency or whenever user interaction happens.

sudo qmassa -m 1000

Showing all DRM clients including the inactive ones (no memory allocated or engines being used).

sudo qmassa -a

Saving the stats to a JSON file.

sudo qmassa -t data.json

Fields description

Per device (on main screen)

The memory usage values are either in bytes (no letter), or in KiB (using "K" letter), or in MiB (using "M" letter), or in GiB (using "G" letter). The values are rounded to be easily displayed in a small space, but if you save the stats to a JSON file you can get them all in bytes.

The overall engines usage depends on the DRM clients that the user has access to. In order to have a system view, please run qmassa as root.

The intention of the power reporting is to have values that are the closest possible to the power usage from both the GPU and the larger package (or card) containing it. It's good to remember that larger package is different on integrated vs discrete GPUs, and there are limitations on what drivers expose and what they have visibility on so expect the information to vary a lot across GPUs and vendors. All the power usage values are in watts (W).

The frequency graph ranges from min to max values and plots the instant driver-requested (if supported) and actual device frequency for each iteration. The graph legend shows the latest value for those frequencies. The graph also indicates the overall status and PL1 throttle reason (for now only valiid on i915 and Xe drivers). All the frequency values are in MHz.

Driver support

The table below shows the current drivers and features supported in qmassa to get device information.

qmassa is tested on some Intel and AMD GPUs but it relies heavily on kernel drivers exposing consistent support across GPUs. If you have a problem, please file an issue so we can debug it.

Limitations

• i915: the kernel driver doesn't track/report system memory used and thus qmassa can't display it.

Per DRM client (on main screen)

The memory usage for DRM clients follow the same format and units as described in the previous per device section. All the values can also be found in bytes when stats are saved to a JSON file.

The engines reported are driver and vendor specific, and are read directly from DRM fdinfo files in /proc.

The CPU usage is measured by how much CPU time that process used versus the total available CPU time across all online CPUs in the system for that iteration. The total available CPU time is the time between two samples multiplied by the number of online CPUs. This allows this value to stay between 0% and 100%.

DRM client screen

The DRM client list can be scrolled up, down, left and right to select a row or to show long command lines. Selecting a row in the list (pressing Enter) opens a screen with just that DRM client stats and charts. In this screen, the memory stats in the table provide some more information (see description below), while the other data is the same as on the main screen.

Acknowledgements

qmassa uses Ratatui for displaying a nice terminal-based UI and leverages many other Rust crates.

License

Copyright © 2024 Ulisses Furquim

This project is distributed under the terms of the Apache License (Version 2.0). See LICENSE for details.