PyXTrace
_{🩺 Your Python program under the microscope – in real time}

^{Byte-code • Memory • (optional) Sys-call tracing  |  Rich CLI + live Streamlit dashboard}

---

🗺️ Table of Contents

• ✨ Features
• 🚀 Installation
• 🕹️ Quick start
• 📂 Project layout
• 🛣️ Road-map
• 👩‍💻 Contributing
• ⚖️ License
• 🙏 Acknowledgements

---

✨ Features

🔍 What you see	💡 Captured via	📈 Visualised as (Streamlit)
Byte-code timeline	sys.settrace	Cumulative line graph
Heap usage (kB)	tracemalloc snapshots	Live line graph
Sys-calls (Linux)	strace -c -p …	Cumulative line graph
Smart commentary	1 s heuristics	Green console panel

macOS & Linux fully supported.
Windows → byte-code + memory tracing (no strace).

---

🚀 Installation

# stable
pip install pyxtrace

# pre-release / nightly
pip install --pre pyxtrace

Optional extras

pip install pyxtrace               # includes the Streamlit dashboard
pip install "pyxtrace[dev]"        # black, ruff, mypy, pytest, …

Linux users – syscall tracing needs strace and root:

sudo apt install strace
sudo pyxtrace --dash your_script.py

or skip sys-calls with --no-syscalls.

---

🕹️ Quick start

# Rich CLI summary only
pyxtrace examples/fibonacci.py

# Live dashboard (opens http://127.0.0.1:8050)
pyxtrace --dash examples/fibonacci.py

# Pass cmd-line args to your script
pyxtrace --dash train.py -- --epochs 10 --lr 3e-4

# Performance presets
pyxtrace --mode demo  script.py   # call/return only   (fastest)
pyxtrace --mode perf  script.py   # skip std-lib lines
pyxtrace --mode full  script.py   # trace everything   (slowest)

When the dashboard opens, press ▶ Start to begin streaming events in real-time. A speed slider lets you throttle or accelerate the playback (10 – 500 events / s).

---

📂 Project layout

src/pyxtrace/
├─ cli.py           ← Typer CLI entry-point
├─ core.py          ← orchestration + JSONL replay
├─ bytecode.py      ← byte-code tracer
├─ memory.py        ← heap sampler (tracemalloc)
├─ syscalls/        ← syscall tracer (Linux / Darwin stubs)
├─ visual.py        ← Rich summary + Streamlit dashboard
└─ …

---

🛣️ Road-map

Status	Item
🔄	Flame-graph view (Chrome-style)
🔄	CPU sample profiler (perf hook)
🔄	Remote dashboard via websockets
🔄	VS Code extension
✅	Streamlit dashboard

---

👩‍💻 Contributing

git clone https://github.com/AbhineetSaha/pyxtrace.git
cd pyxtrace
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pre-commit install

1. Create a feature branch from main
2. Run ./dev_check.py to execute the test suite and linters
3. Open a pull-request ❤️

---

⚖️ License

Released under the MIT License – see LICENSE.

---

🙏 Acknowledgements

Project / Lib	Why it’s awesome
Rich & Typer	Beautiful CLIs with zero boiler-plate
Streamlit & Plotly	Interactive dashboards in pure Python
tracemalloc	Built-in heap sampler, criminally underrated
strace	Decades-old yet still magical

…and you – for trying, starring ⭐ and contributing!