gpu-histop 0.1.0

High-resolution GPU history monitor for NVIDIA, AMDGPU, and Apple Silicon
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121

# gpu-histop

[![CI](https://github.com/sdraeger/gpu-histop/actions/workflows/ci.yml/badge.svg)](https://github.com/sdraeger/gpu-histop/actions/workflows/ci.yml)
[![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

`gpu-histop` is a high-resolution terminal GPU history monitor. It samples GPU
metrics into timestamped ring histories and renders min/max bucketed Braille
graphs, giving each terminal cell a 2x4 subpixel plot.

![gpu-histop terminal preview](assets/demo.svg)

Each GPU panel also includes a compact process overview with process type
(`C`, `G`, or `MPS`), PID, resolved user, GPU memory, command, and MIG instance
IDs when NVML reports them.

## Install

From Homebrew:

```sh
brew tap sdraeger/gpu-histop
brew install gpu-histop
```

From the GitHub repository:

```sh
cargo install --git https://github.com/sdraeger/gpu-histop
```

After publishing the package to crates.io:

```sh
cargo install gpu-histop
```

Prebuilt binaries are attached to tagged GitHub releases for Linux and macOS.

## Backends

- `auto`: use the first available real metrics backend.
- `nvml`: require NVIDIA NVML.
- `nvidia-smi`: use the NVIDIA command line tool when direct NVML loading is not available.
- `amdgpu`: use Linux AMDGPU sysfs metrics.
- `apple`: use Apple Silicon GPU metrics from macOS system tools.

`auto` tries NVML first, then `nvidia-smi`, Linux AMDGPU sysfs, and Apple
Silicon. On Apple Silicon, `auto` starts with the Apple backend so macOS does
not report irrelevant NVIDIA/Linux backend errors. If none of the real backends
is available, startup fails instead of showing generated demo data. The Apple
backend first tries non-root `ioreg` performance counters and falls back to
`powermetrics`, which usually requires administrator privileges on macOS. On
Apple Silicon, GPU memory is unified memory rather than discrete VRAM; when
available, `gpu-histop` reports the GPU-resident unified-memory counters in the
VRAM field.

Apple Silicon power and clock metrics come from `powermetrics`, so they are only
shown when the process has privileges to run that sampler. Recent Apple Silicon
macOS releases generally expose thermal pressure rather than a stable GPU die
temperature in degrees Celsius through built-in command-line tools, so
temperature remains `n/a` unless Apple exposes a Celsius sensor through the
sampled sources. Fan speed is naturally `n/a` on fanless devices.

## Run

Terminal UI:

```sh
gpu-histop --backend auto --sample-ms 100 --window-seconds 60
```

From a source checkout:

```sh
cargo run --release -- --backend auto --sample-ms 100 --window-seconds 60
```

Native GUI:

```sh
cargo run --release --bin gpu-histop-gui -- --backend auto --sample-ms 100 --window-seconds 60
```

The GUI requires an available X11 or Wayland display. On a headless machine,
use the TUI, run with X forwarding, or launch under a virtual display such as
Xvfb.

Probe NVML process reporting without opening the TUI:

```sh
cargo run --example process_probe
```

The GUI shows raw sampled points over the selected history window, one high-density
plot per metric, with a GPU selector and process table for the selected GPU.

Keys:

- `q` or `Esc`: quit
- `Up` / `Down` or `j` / `k`: select a GPU
- `p` or `Enter`: open the process popup for the selected GPU
- `+` / `-`: zoom the visible history window

Process popup keys:

- `Up` / `Down`, `PageUp` / `PageDown`, `Home`, `End`: scroll processes
- `Tab` / `Shift+Tab`: switch GPU
- `Esc`, `p`, or `Enter`: close the popup

## Notes

NVML utilization counters are reported over the hardware sampling period exposed
by the NVIDIA driver, which can be coarser than the poll interval on some GPUs.
`gpu-histop` still keeps monotonic timestamps for every poll and preserves
within-column min/max ranges so spikes remain visible after downsampling to the
terminal.

Some enclosure-cooled NVIDIA data center GPUs do not expose a useful onboard fan
reading through Linux/NVML. When such a device returns a known bogus `0%`/`0 RPM`
fan channel, `gpu-histop` reports fan speed as `n/a` instead of plotting a flat
zero line.