How 1catai/1cat-linkstat works
1CatLinkStat is a Linux/NVIDIA terminal GPU and NVLink monitor, with a separate CUDA peer-to-peer bandwidth benchmark. The primary workflow is CLI options → repeated or one-shot snapshot collection → optional change tracking → terminal or JSON output. Collection combines NVML device/process data with optional live NVLink metrics, topology, and host process details; snapshots are the shared data contract. The README also documents summary, expanded-link, and topology-matrix views. The benchmark’s runtime orchestration is described in the README, but its Python implementation was not sampled.
Main entry points: nvml.py Snapshot Collector · cli.py Monitor CLI · render.py Terminal Renderer · bench.py Benchmark CLI
Components 21
Monitoring
- Monitor CLI
src/cat_linkstat/cli.py - Snapshot Collector
src/cat_linkstat/nvml.py - NVML Access
src/cat_linkstat/nvml.py - DCGM Sampler
src/cat_linkstat/nvml.py - NVLink Sampler
src/cat_linkstat/nvml.py - Topology Sampler
src/cat_linkstat/nvml.py - Process Sampler
src/cat_linkstat/nvml.py - Snapshot Models
src/cat_linkstat/models.py - Change Tracker
src/cat_linkstat/tracking.py
Presentation
- Terminal Renderer
src/cat_linkstat/render.py - Activity History
src/cat_linkstat/render.py
Bandwidth Benchmark
- Benchmark CLI
src/cat_linkstat/bench.py - CUDA Benchmark
src/cat_linkstat/nvlink_microbench.cu
External Interfaces
- NVIDIA GPUs
- NVML Library
- DCGM Tools
- nvidia-smi
- Host Process Tools
- CUDA Toolkit
- Terminal
Other components
- Operator
Connections 28
- Operator → Monitor CLI: sets options
- Monitor CLI → Snapshot Collector: collects snapshot
- Snapshot Collector → NVML Access: reads device data
- NVML Access → NVML Library: calls
- NVML Library → NVIDIA GPUs: queries
- Snapshot Collector → DCGM Sampler: samples totals
- DCGM Sampler → DCGM Tools: queries metrics
- Snapshot Collector → NVLink Sampler: samples NVLink
- NVLink Sampler → nvidia-smi: probes metrics
- Snapshot Collector → Topology Sampler: samples topology
- Topology Sampler → nvidia-smi: reads topology
- Snapshot Collector → Process Sampler: samples processes
- Process Sampler → nvidia-smi: reads GPU processes
- Process Sampler → Host Process Tools: reads process details
- Snapshot Collector → Snapshot Models: builds snapshots
- Monitor CLI → Change Tracker: tracks changes
- Change Tracker → Snapshot Models: compares snapshots
- Monitor CLI → Terminal Renderer: renders views
- Terminal Renderer → Snapshot Models: reads snapshot
- Terminal Renderer → Activity History: updates trends
- Monitor CLI → Snapshot Models: serializes JSON
- Terminal Renderer → Terminal: writes display
- Monitor CLI → Terminal: writes output
- Operator → Benchmark CLI: starts benchmark
- Benchmark CLI → CUDA Toolkit: checks and invokes nvcc
- Benchmark CLI → CUDA Benchmark: builds and runs
- CUDA Benchmark → NVIDIA GPUs: tests peer bandwidth
- Benchmark CLI → Terminal: reports results