nsys-ai 0.2.1

Terminal UI for NVIDIA Nsight Systems profiles — timeline viewer, kernel navigator, NVTX hierarchy

🔬 nsys-ai

Terminal UI for NVIDIA Nsight Systems profiles

Navigate GPU kernel timelines, explore NVTX hierarchies, and analyze performance — all from your terminal.

---

⚡ Install

pip install nsys-ai

That's it. No system dependencies, no CUDA required. Just Python 3.10+.

---

🎯 What It Does

nsys-ai reads .sqlite profile exports from NVIDIA Nsight Systems and gives you three ways to explore them:

🖥️ Timeline TUI Perfetto-style horizontal timeline in your terminal	🌲 Tree TUI Interactive NVTX hierarchy browser with kernel details	🌐 HTML Viewer Exportable interactive visualizations for sharing
S21 ████░██████░███ S56 ██████░░░███████ S60 ░░░██████░░░░░██ | │ 39.1s 39.5s	▼ Iteration (324ms) ▼ forward (180ms) ▼ Attention (89ms) ■ flash_fwd 26ms ■ flash_bwd 63ms	Interactive HTML exports: • NVTX stack viewer • SQLite schema explorer • Perfetto JSON traces

---

🚀 Quick Start

1. Get a profile

# Profile your PyTorch training
nsys profile -o my_training python train.py
# → produces my_training.sqlite

2. Explore it

# Quick overview
nsys-ai info my_training.sqlite

# Interactive timeline (the main attraction)
nsys-ai timeline my_training.sqlite --gpu 0 --trim 39 42

# Interactive tree browser
nsys-ai tui my_training.sqlite --gpu 0 --trim 39 42

# GPU kernel summary
nsys-ai summary my_training.sqlite --gpu 0

3. Export & share

# Perfetto JSON (open in ui.perfetto.dev)
nsys-ai export my_training.sqlite -o traces/

# Interactive HTML viewer
nsys-ai viewer my_training.sqlite --gpu 0 --trim 39 42 -o report.html

# Flat CSV/JSON for scripting
nsys-ai export-csv my_training.sqlite --gpu 0 --trim 39 42 -o kernels.csv

---

⌨️ Timeline TUI

The timeline is a Perfetto-style horizontal viewer with per-stream kernel visualization, NVTX hierarchy bars, and a time-cursor navigation model.

Navigation

Key	Action
← →	Pan through time
Shift+←/→	Page pan (1/4 viewport)
↑ ↓	Select stream
Tab	Snap to next kernel
+ -	Zoom in / out
a	Toggle absolute ↔ relative time

Analysis

Key	Action
/	Filter kernels by name
m	Set minimum duration threshold
d	Toggle demangled kernel names
C	Open config panel
h	Full help overlay

Bookmarks

Key	Action
B	Save bookmark (with kernel + NVTX context)
'	Bookmark list — press 1-9 to jump
, .	Cycle through bookmarks
`	Jump back to previous position
[ ]	Set range start / end

Config Panel (C)

Tweak settings live with ↑/↓ to select and ←/→ to adjust:

• Selected stream rows (1-6)
• Other stream rows (1-4)
• Time tick density (2-20)
• NVTX depth levels (0-8)
• Min kernel duration filter

---

📚 Documentation

The docs/ directory includes comprehensive guides for Nsight Systems profiling:

Guide	Topic
CLI Reference	Full nsys command reference
SQLite Schema	Database tables & relationships
NVTX Annotations	Adding markers to your code
CUDA Trace	GPU kernel tracing
NCCL Tracing	Multi-GPU collective analysis
Python/PyTorch	Profiling PyTorch workloads
Containers	Profiling inside Docker/Slurm
Focused Profiling	Targeted profiling strategies

🔍 Interactive SQLite Schema Explorer

The docs/sqlite-explorer/ contains an interactive HTML tool for exploring the Nsight SQLite schema — tables, foreign keys, example queries, and key concepts. Open docs/sqlite-explorer/index.html in a browser:

• Browse all Nsight SQLite tables with column types
• See foreign key relationships visualized
• Copy-paste ready SQL query examples
• Cross-highlighted concept explanations

---

🛠️ All Commands

Command	Description
info	Profile metadata & GPU hardware
summary	Top kernels, stream breakdown, auto-commentary
overlap	Compute / NCCL overlap analysis
nccl	NCCL collective breakdown by type
iters	Auto-detect training iterations
tree	NVTX hierarchy as text
tui	Interactive tree TUI
timeline	Interactive timeline TUI
search	Search kernels / NVTX by name
export	Perfetto JSON traces
export-csv	Flat CSV for spreadsheets
export-json	Flat JSON for scripting
viewer	Interactive HTML report
markdown	NVTX hierarchy as markdown

---

🤖 AI Analysis (Optional)

nsys-ai includes an optional AI module that can analyze your profiles:

pip install nsys-ai[ai]

• Auto-commentary on kernel distributions and performance patterns
• NVTX annotation suggestions for un-annotated code regions
• Performance bottleneck detection with actionable recommendations

---

🧑‍💻 Development

git clone https://github.com/GindaChen/nsys-ai.git
cd nsys-ai
pip install -e '.[dev]'
pytest tests/ -v

---

📄 License

MIT — see LICENSE.

_{Built for GPU performance engineers who live in the terminal.}