dltop 0.2.0__tar.gz

dltop-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nikhil
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

dltop-0.2.0/PKG-INFO

@@ -0,0 +1,172 @@
+Metadata-Version: 2.4
+Name: dltop
+Version: 0.2.0
+Summary: top/htop-style GPU monitor for CV and AI workloads -- splits CUDA/Tensor/FP* compute from NVENC/NVDEC media engines
+Author-email: Nikhil <nikhil@detecttechnologies.com>
+Project-URL: Homepage, https://github.com/rsnk96/dltop
+Project-URL: Repository, https://github.com/rsnk96/dltop
+Project-URL: Issues, https://github.com/rsnk96/dltop/issues
+Keywords: gpu,monitoring,nvidia,cuda,tui,dcgm,nvml,computer-vision,deep-learning
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Environment :: GPU :: NVIDIA CUDA
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: loguru>=0.7
+Requires-Dist: nvidia-ml-py>=12.0
+Requires-Dist: psutil>=5.9
+Requires-Dist: rich>=13.0
+Requires-Dist: textual>=0.60
+Provides-Extra: test
+Requires-Dist: pytest>=8.0; extra == "test"
+Requires-Dist: pytest-asyncio>=0.23; extra == "test"
+Provides-Extra: screenshots
+Requires-Dist: cairosvg>=2.7; extra == "screenshots"
+Dynamic: license-file
+
+# dltop
+
+A `htop`/`nvitop`-style GPU monitor, tailored for computer-vision and deep-learning workloads.
+
+Where `nvitop` gives you one uniform compute-utilization bar, `dltop` splits live GPU utilization into the two things an AI/CV engineer actually cares about on the same GPU:
+
+- **Compute utilization** — CUDA Streaming Multiprocessor / Tensor / FP32 / FP16 / FP64 activity (via DCGM)
+- **Media engines** — NVENC (encode) and NVDEC (decode) throughput (via NVML)
+
+This helps identify the choke point for different scales of load on a streaming-analytics pipeline. Many metrics share **one interleaved chart** instead of stacking into tall bars: overlapping series alternate colour cell-by-cell, so no line is ever hidden behind another while each keeps its true value.
+
+When DCGM is unavailable (consumer GeForce cards, or DCGM not installed), `dltop` falls back to NVML's single lumped SM% (the aggregate compute-utilization proxy shown by `nvidia-smi`) and prints a footer telling you how to enable the full split on a data-center GPU.
+
+### Multi-GPU
+
+Every chart is grouped **one domain per GPU** — never mixed onto a shared axis. On a box with more than one GPU, `dltop` adds a host chart plus one chart per GPU per tab (so a 2-GPU box shows 3 stacked charts on the Compute tab: Host, GPU 0, GPU 1), an info card row per GPU, and a toggle bar to show/hide individual GPUs across every chart at once.
+
+## Screenshots
+
+Captured in `--demo` mode (synthetic 2-GPU telemetry — see [Demo mode](#demo-mode-no-gpu-needed)). Five tabs, all on one shared time-series axis.
+
+### All
+The default overview — every metric on one axis, with **CPU, RAM, GPU SM and GPU VRAM** on by default. Glance once: is anything busy?
+
+<img src="https://raw.githubusercontent.com/rsnk96/dltop/main/assets/screenshots/all.png" alt="dltop — All tab" width="100%">
+
+### Compute
+Host CPU plus the GPU compute engines. On data-center GPUs the DCGM split breaks SM into **Tensor, FP32, FP16 and FP64** — see exactly which math your model is doing.
+
+<img src="https://raw.githubusercontent.com/rsnk96/dltop/main/assets/screenshots/compute.png" alt="dltop — Compute tab" width="100%">
+
+### Memory
+Host **RAM**, GPU **VRAM** and **VRAM bandwidth** — watch memory fill as a model loads and catch bandwidth saturation.
+
+<img src="https://raw.githubusercontent.com/rsnk96/dltop/main/assets/screenshots/memory.png" alt="dltop — Memory tab" width="100%">
+
+### System
+**PCIe** in/out, GPU **power** draw, **disk** and **network** — the plumbing around the GPU.
+
+<img src="https://raw.githubusercontent.com/rsnk96/dltop/main/assets/screenshots/system.png" alt="dltop — System tab" width="100%">
+
+### Table
+Every series — host, per-GPU, and any auto-discovered Prometheus metric — as a row of rolling-window stats (**Now, Mean, Median, Stddev**) over the last `--window` seconds. Four buttons copy the current snapshot straight to the clipboard: **Markdown**, **web table (HTML)**, **Excel (TSV)**, or a **capture-metadata** block (timestamp, dltop version, hostname, OS, CPU, RAM, GPU(s), driver/CUDA versions, and any Prometheus endpoints) — handy for pasting into a bug report or a training-run log.
+
+<img src="https://raw.githubusercontent.com/rsnk96/dltop/main/assets/screenshots/table.png" alt="dltop — Table tab" width="100%">
+
+> The screenshots above are stored via [Git LFS](https://git-lfs.com), so a plain clone (or a `pip install` from Git) only pulls tiny pointer files unless you explicitly fetch the LFS objects. Regenerate them anytime with `pip install -e ".[screenshots]"` then `python scripts/capture_screenshots.py`.
+
+## Installation
+
+### From PyPI (recommended)
+
+```bash
+pipx install dltop
+```
+
+[`pipx`](https://pipx.pypa.io) installs `dltop` into its own isolated environment while still putting the `dltop` command on your `PATH` — the right way to install a standalone CLI tool. A plain `pip install` works too:
+
+```bash
+pip install dltop
+```
+
+### For development
+
+```bash
+git clone https://github.com/rsnk96/dltop && cd dltop
+pip install -e ".[test]"
+```
+
+Python 3.11+ required. The tool is Linux-only (needs NVML + optionally `dcgmi`).
+
+## Usage
+
+Once installed, `dltop` is callable from any directory — the same way `htop` is:
+
+```bash
+dltop                   # 0.5s refresh, DCGM if available
+dltop -i 1              # 1s refresh
+dltop --no-dcgm         # NVML-only (skip DCGM even if installed)
+dltop --window 120      # stats window for the Table tab, seconds (default 60)
+dltop --no-discover     # disable Prometheus /metrics auto-discovery
+dltop --demo            # synthetic 2-GPU telemetry, no NVIDIA hardware needed
+dltop --demo 4          # synthetic N-GPU telemetry
+dltop --version         # print the installed version and exit
+dltop --help
+```
+
+### Key bindings (in the TUI)
+
+| Key | Action |
+|---|---|
+| `q`, `Q` | Quit |
+| `space`, `p` | Pause / resume sampling |
+
+Switch tabs (**All · Compute · Memory · System · Table**) by clicking them, or with `←` / `→` when the tab bar is focused. Each chart has per-series checkboxes underneath to toggle individual lines on or off.
+
+### Demo mode (no GPU needed)
+
+`--demo [N]` swaps NVML/DCGM for a synthetic `N`-GPU source (default 2) so you can try, develop, or screenshot `dltop` on a laptop with no NVIDIA hardware at all — it's also what `scripts/capture_screenshots.py` uses to generate the images above.
+
+### Prometheus auto-discovery
+
+On startup (unless `--no-discover` is passed), `dltop` enumerates locally listening TCP ports (via `psutil`, falling back to `ss -lnt`), probes each with a short-timeout `GET /metrics`, and treats any response that looks like Prometheus text-exposition format as a hit. Up to 30 gauge/counter metrics per discovered endpoint are added as extra, default-off series on the **All** tab, scraped on a background thread every `max(--interval, 1)` seconds. Histograms and summaries are skipped (their component series aren't meaningful as single lines). Disable the whole probe with `--no-discover` if you'd rather not have `dltop` touch other local sockets.
+
+## Related projects
+
+`dltop` owes a lot to the terminal monitors that came before it:
+
+- [htop](https://htop.dev) — the classic interactive process and CPU monitor.
+- [btop](https://github.com/aristocratos/btop) — a polished all-round system monitor (CPU, memory, disk, network).
+- [nvtop](https://github.com/Syllo/nvtop) — an htop-style monitor for AMD / NVIDIA / Intel GPUs.
+- [nvitop](https://github.com/XuehaiPan/nvitop) — an interactive NVIDIA GPU process viewer.
+
+We use and admire all of these. None of them, individually or together, met the needs we had internally: a single view that splits GPU compute into the lanes a CV/AI engineer reasons about — SM, Tensor, FP16/FP32/FP64 — **and** the media engines (NVENC/NVDEC), overlaid against host CPU/RAM/IO on one time-series, so you can see where a streaming-analytics pipeline actually bottlenecks. So we built `dltop`.
+
+## Enabling the full compute split (DCGM)
+
+On a data-center GPU (A100, H100, L4, T4, etc.) you can install DCGM to unlock the per-lane breakdown:
+
+```bash
+# Ubuntu / Debian
+sudo apt install datacenter-gpu-manager
+sudo systemctl --now enable nvidia-dcgm
+```
+
+Consumer GeForce cards (RTX 4090, 3090, etc.) have these profiling fields gated by NVIDIA at the driver level — DCGM will install but return no profiling data. `dltop` detects this at startup and falls back silently.
+
+## Runtime requirements
+
+- NVIDIA driver + CUDA runtime (any version supported by `nvidia-ml-py`)
+- DCGM service (optional, for the full compute-lane split)
+- A terminal (TTY) if you want the keyboard shortcuts — piping to a non-TTY still renders frames but disables keystroke handling
+
+## License
+
+MIT

dltop-0.2.0/README.md

@@ -0,0 +1,136 @@
+# dltop
+
+A `htop`/`nvitop`-style GPU monitor, tailored for computer-vision and deep-learning workloads.
+
+Where `nvitop` gives you one uniform compute-utilization bar, `dltop` splits live GPU utilization into the two things an AI/CV engineer actually cares about on the same GPU:
+
+- **Compute utilization** — CUDA Streaming Multiprocessor / Tensor / FP32 / FP16 / FP64 activity (via DCGM)
+- **Media engines** — NVENC (encode) and NVDEC (decode) throughput (via NVML)
+
+This helps identify the choke point for different scales of load on a streaming-analytics pipeline. Many metrics share **one interleaved chart** instead of stacking into tall bars: overlapping series alternate colour cell-by-cell, so no line is ever hidden behind another while each keeps its true value.
+
+When DCGM is unavailable (consumer GeForce cards, or DCGM not installed), `dltop` falls back to NVML's single lumped SM% (the aggregate compute-utilization proxy shown by `nvidia-smi`) and prints a footer telling you how to enable the full split on a data-center GPU.
+
+### Multi-GPU
+
+Every chart is grouped **one domain per GPU** — never mixed onto a shared axis. On a box with more than one GPU, `dltop` adds a host chart plus one chart per GPU per tab (so a 2-GPU box shows 3 stacked charts on the Compute tab: Host, GPU 0, GPU 1), an info card row per GPU, and a toggle bar to show/hide individual GPUs across every chart at once.
+
+## Screenshots
+
+Captured in `--demo` mode (synthetic 2-GPU telemetry — see [Demo mode](#demo-mode-no-gpu-needed)). Five tabs, all on one shared time-series axis.
+
+### All
+The default overview — every metric on one axis, with **CPU, RAM, GPU SM and GPU VRAM** on by default. Glance once: is anything busy?
+
+<img src="https://raw.githubusercontent.com/rsnk96/dltop/main/assets/screenshots/all.png" alt="dltop — All tab" width="100%">
+
+### Compute
+Host CPU plus the GPU compute engines. On data-center GPUs the DCGM split breaks SM into **Tensor, FP32, FP16 and FP64** — see exactly which math your model is doing.
+
+<img src="https://raw.githubusercontent.com/rsnk96/dltop/main/assets/screenshots/compute.png" alt="dltop — Compute tab" width="100%">
+
+### Memory
+Host **RAM**, GPU **VRAM** and **VRAM bandwidth** — watch memory fill as a model loads and catch bandwidth saturation.
+
+<img src="https://raw.githubusercontent.com/rsnk96/dltop/main/assets/screenshots/memory.png" alt="dltop — Memory tab" width="100%">
+
+### System
+**PCIe** in/out, GPU **power** draw, **disk** and **network** — the plumbing around the GPU.
+
+<img src="https://raw.githubusercontent.com/rsnk96/dltop/main/assets/screenshots/system.png" alt="dltop — System tab" width="100%">
+
+### Table
+Every series — host, per-GPU, and any auto-discovered Prometheus metric — as a row of rolling-window stats (**Now, Mean, Median, Stddev**) over the last `--window` seconds. Four buttons copy the current snapshot straight to the clipboard: **Markdown**, **web table (HTML)**, **Excel (TSV)**, or a **capture-metadata** block (timestamp, dltop version, hostname, OS, CPU, RAM, GPU(s), driver/CUDA versions, and any Prometheus endpoints) — handy for pasting into a bug report or a training-run log.
+
+<img src="https://raw.githubusercontent.com/rsnk96/dltop/main/assets/screenshots/table.png" alt="dltop — Table tab" width="100%">
+
+> The screenshots above are stored via [Git LFS](https://git-lfs.com), so a plain clone (or a `pip install` from Git) only pulls tiny pointer files unless you explicitly fetch the LFS objects. Regenerate them anytime with `pip install -e ".[screenshots]"` then `python scripts/capture_screenshots.py`.
+
+## Installation
+
+### From PyPI (recommended)
+
+```bash
+pipx install dltop
+```
+
+[`pipx`](https://pipx.pypa.io) installs `dltop` into its own isolated environment while still putting the `dltop` command on your `PATH` — the right way to install a standalone CLI tool. A plain `pip install` works too:
+
+```bash
+pip install dltop
+```
+
+### For development
+
+```bash
+git clone https://github.com/rsnk96/dltop && cd dltop
+pip install -e ".[test]"
+```
+
+Python 3.11+ required. The tool is Linux-only (needs NVML + optionally `dcgmi`).
+
+## Usage
+
+Once installed, `dltop` is callable from any directory — the same way `htop` is:
+
+```bash
+dltop                   # 0.5s refresh, DCGM if available
+dltop -i 1              # 1s refresh
+dltop --no-dcgm         # NVML-only (skip DCGM even if installed)
+dltop --window 120      # stats window for the Table tab, seconds (default 60)
+dltop --no-discover     # disable Prometheus /metrics auto-discovery
+dltop --demo            # synthetic 2-GPU telemetry, no NVIDIA hardware needed
+dltop --demo 4          # synthetic N-GPU telemetry
+dltop --version         # print the installed version and exit
+dltop --help
+```
+
+### Key bindings (in the TUI)
+
+| Key | Action |
+|---|---|
+| `q`, `Q` | Quit |
+| `space`, `p` | Pause / resume sampling |
+
+Switch tabs (**All · Compute · Memory · System · Table**) by clicking them, or with `←` / `→` when the tab bar is focused. Each chart has per-series checkboxes underneath to toggle individual lines on or off.
+
+### Demo mode (no GPU needed)
+
+`--demo [N]` swaps NVML/DCGM for a synthetic `N`-GPU source (default 2) so you can try, develop, or screenshot `dltop` on a laptop with no NVIDIA hardware at all — it's also what `scripts/capture_screenshots.py` uses to generate the images above.
+
+### Prometheus auto-discovery
+
+On startup (unless `--no-discover` is passed), `dltop` enumerates locally listening TCP ports (via `psutil`, falling back to `ss -lnt`), probes each with a short-timeout `GET /metrics`, and treats any response that looks like Prometheus text-exposition format as a hit. Up to 30 gauge/counter metrics per discovered endpoint are added as extra, default-off series on the **All** tab, scraped on a background thread every `max(--interval, 1)` seconds. Histograms and summaries are skipped (their component series aren't meaningful as single lines). Disable the whole probe with `--no-discover` if you'd rather not have `dltop` touch other local sockets.
+
+## Related projects
+
+`dltop` owes a lot to the terminal monitors that came before it:
+
+- [htop](https://htop.dev) — the classic interactive process and CPU monitor.
+- [btop](https://github.com/aristocratos/btop) — a polished all-round system monitor (CPU, memory, disk, network).
+- [nvtop](https://github.com/Syllo/nvtop) — an htop-style monitor for AMD / NVIDIA / Intel GPUs.
+- [nvitop](https://github.com/XuehaiPan/nvitop) — an interactive NVIDIA GPU process viewer.
+
+We use and admire all of these. None of them, individually or together, met the needs we had internally: a single view that splits GPU compute into the lanes a CV/AI engineer reasons about — SM, Tensor, FP16/FP32/FP64 — **and** the media engines (NVENC/NVDEC), overlaid against host CPU/RAM/IO on one time-series, so you can see where a streaming-analytics pipeline actually bottlenecks. So we built `dltop`.
+
+## Enabling the full compute split (DCGM)
+
+On a data-center GPU (A100, H100, L4, T4, etc.) you can install DCGM to unlock the per-lane breakdown:
+
+```bash
+# Ubuntu / Debian
+sudo apt install datacenter-gpu-manager
+sudo systemctl --now enable nvidia-dcgm
+```
+
+Consumer GeForce cards (RTX 4090, 3090, etc.) have these profiling fields gated by NVIDIA at the driver level — DCGM will install but return no profiling data. `dltop` detects this at startup and falls back silently.
+
+## Runtime requirements
+
+- NVIDIA driver + CUDA runtime (any version supported by `nvidia-ml-py`)
+- DCGM service (optional, for the full compute-lane split)
+- A terminal (TTY) if you want the keyboard shortcuts — piping to a non-TTY still renders frames but disables keystroke handling
+
+## License
+
+MIT

dltop-0.2.0/dltop/__init__.py

@@ -0,0 +1,22 @@
+"""dltop -- a top/htop-style GPU monitor tailored for CV and AI workloads.
+
+Splits live GPU utilization into two categories:
+
+    * Compute (CV/AI): SM active, Tensor pipe, FP32/FP16/FP64 pipes -- via DCGM profiling
+    * Media engines: NVENC, NVDEC -- via NVML
+
+The UI is built on Textual with box-drawing line charts (the nvtop/asciichart
+look), so many metrics share one chart instead of stacking into tall bars.
+Overlapping series are colour-interleaved per column so no line is ever hidden
+behind another while every line keeps its true value (see ``TimeSeriesPlot``).
+
+When DCGM profiling metrics are unavailable (e.g. consumer GeForce cards where
+NVIDIA gates profiling fields, or DCGM not installed), we transparently fall
+back to NVML's single overall SM% and show a status banner telling the user how
+to enable the full split on a data-center GPU.
+"""
+
+from dltop._version import __version__
+from dltop.cli import main
+
+__all__ = ["__version__", "main"]

dltop-0.2.0/dltop/__main__.py

@@ -0,0 +1,6 @@
+"""Allow `python -m dltop`."""
+
+from dltop.cli import main
+
+if __name__ == "__main__":
+    main()

dltop-0.2.0/dltop/_version.py

@@ -0,0 +1,8 @@
+"""Single source of the installed package version."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("dltop")
+except PackageNotFoundError:  # running from a checkout without an install
+    __version__ = "0.0.0+uninstalled"