dgxtop

KO | EN

Minimalist Open Source Repository Search Engine

gitlite — search

#typescript #ai-agents #open-source #ai #cli #deepseek-harness #dsh-plugin #claude-code #react #windows #codex #developer-tools

★ 66 Open GitHub ↗

High-performance interactive system monitor for NVIDIA DGX systems — GPU, CPU, memory, disk, network in a beautiful TUI

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# dgxtop

![dgxtop — Overview on DGX Spark](https://raw.githubusercontent.com/DennySORA/dgxtop/main/docs/screenshot-overview.png)

[繁體中文](docs/README.zh-TW.md) | [简体中文](docs/README.zh-CN.md) | [日本語](docs/README.ja.md)

> High-performance, interactive system monitor for NVIDIA DGX systems with real-time GPU, CPU, memory, disk capacity/I/O, and network monitoring.

[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](https://raw.githubusercontent.com/DennySORA/dgxtop/main/LICENSE)
[![Rust](https://img.shields.io/badge/rust-1.92%2B-orange.svg)](https://www.rust-lang.org/)
[![CI](https://github.com/DennySORA/dgxtop/actions/workflows/ci.yml/badge.svg)](https://github.com/DennySORA/dgxtop/actions/workflows/ci.yml)
[![Release](https://github.com/DennySORA/dgxtop/actions/workflows/release.yml/badge.svg)](https://github.com/DennySORA/dgxtop/releases)

**dgxtop** is a comprehensive system monitoring tool purpose-built for NVIDIA DGX infrastructure. It provides real-time visibility into GPU utilization, VRAM, temperature, power draw, NVLink topology, disk usage, and system resources — all in an interactive terminal UI. Built in Rust with direct NVML access for maximum performance and reliability.

## Quick Install

```bash
curl -fsSL https://raw.githubusercontent.com/DennySORA/dgxtop/main/install.sh | bash
```

See [Installation](#installation) for more options.

## Why dgxtop?

- **Direct NVML Access** — Reads GPU metrics through NVIDIA Management Library, not nvidia-smi subprocess calls. Faster, more reliable, and more detailed.
- **DGX-Optimized** — Supports multi-GPU monitoring, NVLink topology, ECC error tracking, and PCIe throughput — features critical for DGX A100/H100/B200 and DGX Spark.
- **Full System View** — CPU per-core utilization, memory (RAM + Swap), disk capacity (Used / Free / Use%) plus I/O, and network interfaces in a single dashboard.
- **Interactive Process Management** — Sort, filter, and kill GPU processes directly from the TUI. See per-process GPU utilization, VRAM usage, and host memory.
- **Secure by Design** — No subprocess shell-outs, PID recycling protection, config value sanitization, and UTF-8 safe rendering. Passed deep security audit.

## Features

### GPU Monitoring (via NVML)

| Category | Metrics |
|----------|---------|
| **Utilization** | GPU %, Memory controller %, per-process SM utilization |
| **Memory** | VRAM used/total/free, BAR1 usage, per-process GPU memory |
| **Bandwidth** | Memory bandwidth utilization (actual/theoretical GB/s), unified-memory auto-detection (LPDDR5X), PCIe TX/RX throughput with 1/6/12/24h avg/max stats |
| **Thermal** | Temperature (with slowdown/shutdown thresholds), fan speed, 1/6/12/24h avg/max |
| **Power** | Draw/limit (watts), usage %, total energy consumption (kWh), 1/6/12/24h avg/max/cumulative energy |
| **Clock** | Graphics, SM, Memory, Video frequencies (current/max MHz) |
| **State** | Performance state (P0–P15), throttle reasons, compute mode, persistence mode |
| **Health** | ECC errors (corrected/uncorrected), retired pages (SBE/DBE) |
| **Topology** | NVLink active links with remote GPU mapping, PCIe Gen/Width |
| **Codec** | Encoder/Decoder utilization % |
| **Identity** | UUID, serial number |

### System Monitoring

| Category | Metrics |
|----------|---------|
| **CPU** | Aggregate and per-core usage (htop-style), user/system/iowait breakdown, temperature, power draw, frequency, **load average** (1/5/15m), **tasks** (running/total) |
| **Memory** | RAM used/total, buffers, cached, available, swap usage |
| **Disk Capacity & I/O** | Filesystem usage for mounted devices (Used / Free / Use%), per-device read/write throughput, IOPS, await latency, sorted by throughput |
| **Network** | Per-interface RX/TX throughput, errors, sorted by activity |

### Time-Series Analytics

- **Line charts** for GPU utilization, memory, temperature, and power with Braille markers
- **1/6/12/24h statistics** — avg/max for CPU, Memory, GPU utilization, temperature, power (with cumulative kWh), memory, PCIe TX/RX; avg R/W for Disk; cumulative ↓/↑ for Network
- **Progressive display** — stats windows only appear after enough data has been collected
- **Minute-resolution aggregation** — memory-efficient 24h storage (~28KB per metric)

### Interactive TUI

- **Three Views** — Overview dashboard, GPU detail (full-page per-GPU), full-screen process table
- **Vim Keybindings** — Navigate with `j/k`, switch tabs with `1/2/3`, GPU selection with `h/l`
- **Device Selection** — Cycle network interfaces (`n/N`), disk devices (`d/D`) with chart/stats following selection
- **Process Management** — Sort by GPU mem/utilization/CPU/PID, filter by name, kill with confirmation
- **Responsive Layout** — Auto-adapts to terminal size, conditionally shows charts/stats based on available space
- **Visual Design** — Rounded panels, gradient gauges, line charts, alternating row colors, color-coded thresholds

#### Multi-GPU Overview with Active Workloads

![dgxtop — Multi-GPU with active workloads](https://raw.githubusercontent.com/DennySORA/dgxtop/main/docs/screenshot-multi-gpu.png)

## Installation

### Quick Install (Recommended)

```bash
curl -fsSL https://raw.githubusercontent.com/DennySORA/dgxtop/main/install.sh | bash
```

The installer auto-detects your libc and picks the matching release target.
For NVIDIA GPU metrics, glibc (`-gnu`) builds are recommended.

### Download Binary

Download pre-built binaries from [GitHub Releases](https://github.com/DennySORA/dgxtop/releases):

| Platform | Architecture | Download |
|----------|--------------|----------|
| Linux | x86_64 (glibc, recommended) | `dgxtop-x86_64-unknown-linux-gnu.tar.gz` |
| Linux | x86_64 (musl, compatibility) | `dgxtop-x86_64-unknown-linux-musl.tar.gz` |
| Linux | ARM64 (glibc, recommended) | `dgxtop-aarch64-unknown-linux-gnu.tar.gz` |
| Linux | ARM64 (musl, compatibility) | `dgxtop-aarch64-unknown-linux-musl.tar.gz` |

> Note: On some systems, musl builds may fail to load NVIDIA NVML (`libnvidia-ml.so`), resulting in missing GPU metrics.

### Build from Source

```bash
git clone https://github.com/DennySORA/dgxtop.git
cd dgxtop
cargo build --release
# Binary: target/release/dgxtop
```

### Cargo Install

```bash
cargo install --git https://github.com/DennySORA/dgxtop.git
```

## Usage

### Basic Usage

```bash
# Start with default settings
dgxtop

# Custom refresh interval (0.5 seconds)
dgxtop -i 0.5

# Disable GPU monitoring (system metrics only)
dgxtop --no-gpu

# Use green color theme
dgxtop -t green
```

### Command Line Options

| Option | Description | Default |
|--------|-------------|---------|
| `-i, --interval <SECS>` | Update interval in seconds (0.1–10.0) | `1.0` |
| `-t, --theme <NAME>` | Color theme: `cyan`, `green`, `amber` | `cyan` |
| `--no-gpu` | Disable GPU monitoring | `false` |
| `--net-max <N>` | Max visible network interfaces / disk devices (1–20) | `3` |
| `--log-level <LEVEL>` | Log level: `error`, `warn`, `info`, `debug` | `warn` |

### Keyboard Shortcuts

| Key | Action |
|-----|--------|
| `q` / `Ctrl+C` | Quit |
| `Tab` / `Shift+Tab` | Switch between views |
| `1` / `2` / `3` | Jump to Overview / GPU Detail / Processes |
| `j/k` or `↑/↓` | Navigate up/down |
| `h/l` or `←/→` | Select GPU (in GPU Detail view) |
| `s` | Enter sort mode |
| `r` | Reverse sort order (in sort mode) |
| `/` | Filter processes by name/PID/user |
| `K` | Kill selected process (with confirmation) |
| `e` | Toggle per-core CPU view (htop-style) |
| `n` / `N` | Cycle network interface |
| `d` / `D` | Cycle disk device |
| `+` / `-` | Increase / decrease refresh speed |
| `?` | Toggle help overlay |

### Views

**Overview** — Responsive dashboard with CPU gauge (temperature, power draw, load average, tasks, htop per-core toggle), memory bars, GPU cards, disk capacity + I/O, and network panels with line charts and 1/6/12/24h statistics. The disk table shows Used / Free / Use% for mounted filesystems, with read/write throughput, IOPS, and await latency still tracked per device. Device selection highlights chart/stats for the chosen interface or disk.

**GPU Detail** — Full-page single-GPU view with comprehensive metrics: utilization, VRAM, **memory bandwidth** (actual/theoretical GB/s), BAR1, thermal (with thresholds), power (with energy kWh), **throttle reasons**, P-state, all clock domains (Graphics/SM/Memory/Video), PCIe info, **NVLink topology**, encoder/decoder, ECC, retired pages, compute mode, UUID — plus time-series charts and per-GPU process list.

![dgxtop — GPU Detail view](https://raw.githubusercontent.com/DennySORA/dgxtop/main/docs/screenshot-gpu-detail.png)

**Processes** — Full-screen GPU process table with sortable columns, search filter, and process kill capability. Shows PID, user, GPU device, type, GPU%, VRAM, CPU%, host memory, and command.

![dgxtop — Processes view](https://raw.githubusercontent.com/DennySORA/dgxtop/main/docs/screenshot-processes.png)

## Architecture

```
┌─────────────────────────────────────────────────────────────────────┐
│                           Main Thread                               │
│  ┌───────────┐    ┌────────────┐    ┌────────────────────────────┐ │
│  │  AppState  │◄───│  UI Loop   │◄───│ crossbeam channel (rx)    │ │
│  │            │    │  (ratatui) │    │ bounded(256)               │ │
│  └───────────┘    └────────────┘    └────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────┘
                                                ▲
                     Tick events + Key/Mouse    │
                                                │
┌───────────────────────────────────────────────┴─────────────────────┐
│                        Event Thread                                  │
│  ┌───────────────────────────────────────────────────────────────┐  │
│  │  crossterm::event::poll + Tick timer → AppEvent → channel tx  │  │
│  └───────────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────────┘

Collectors (called on each Tick):
  ├── GpuCollector        (NVML: utilization, temp, power, clocks, memory, bandwidth,
  │                         ECC, PCIe, NVLink, BAR1, throttle, P-state, encoder/decoder,
  │                         retired pages, energy, UUID, serial)
  ├── GpuProcessCollector (NVML + /proc: per-process GPU/CPU/memory stats)
  ├── CpuCollector        (/proc/stat + /proc/loadavg + powercap/hwmon: per-core usage,
  │                         frequency, temperature, power draw, load average, task count)
  ├── MemoryCollector     (/proc/meminfo: RAM, swap, buffers, cached)
  ├── DiskCollector       (/proc/diskstats + /sys/class/block + mountinfo/statvfs:
  │                         filesystem Used/Free/Use%, per-device throughput, IOPS, latency)
  └── NetworkCollector    (/sys/class/net: per-interface RX/TX, packets, errors)

History (per metric):
  ├── RingBuffer          (short-term: 300 samples for charts)
  └── TimeWindowAggregator (long-term: minute-resolution buckets for 24h stats)
```

## Requirements

- **OS**: Linux (DGX systems, WSL2, containers)
- **GPU**: NVIDIA drivers with NVML (libnvidia-ml.so)
- **Runtime**: No additional dependencies. For GPU monitoring, prefer glibc (`-gnu`) builds.

## Security

dgxtop has undergone a comprehensive security audit addressing:
- UTF-8 boundary safety in all string rendering
- PID recycling protection with pre-kill verification
- Integer overflow protection with saturating arithmetic
- Path traversal prevention in filesystem readers
- Config value sanitization against NaN/Infinity/DoS
- Bounded event channels to prevent memory exhaustion

See commit history for the full audit report and fixes.

## License

Apache License 2.0 — see [LICENSE](LICENSE) for details.

## Contributing

Contributions welcome! Please feel free to submit issues and pull requests.

dgxtop

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README