glassbox

Live Python execution profiler and visualizer. Point it at a script or a whole project and watch it run — which line is executing right now, where memory piles up, which functions burn the most CPU, and what's blocking your asyncio loop — all streamed in real time to your browser.

glassbox runs your target in-process under sys.setprofile plus a statistical line sampler and tracemalloc, and streams telemetry over websockets to an animated single-page UI.

---

Screenshots

Live — the executing line, per-line heat, live call stack, and leveled output:

Profile — function benchmarks (self / CPU / total), CPU timeline, hot lines, and the asyncio event-loop blocker:

Memory — RSS / heap timeline, tracemalloc allocation hotspots, growth-since-baseline, and per-variable sizes:

Flame — a time-proportional call tree, click any frame to zoom:

Flow — an animated 3D call graph with blips streaming along the live call path:

Files — which file calls into which, with live call blips between files:

---

Features

• Live source view — highlights the line executing in real time, with a per-line heat map of where time is spent, and follows execution across files.
• Call stack — the current frame chain, updated live without strobing.
• Leveled output — captures print() and the logging module, tagged and filterable by level (debug/info/warn/error/crit).
• Function benchmarks — per-function calls, self time, CPU time, and total time, sorted and filterable. Wall − CPU exposes time spent waiting on I/O, sleep, locks or the GIL.
• Hot lines — the source lines the sampler caught executing most often.
• Memory — a live RSS / Python-heap timeline, tracemalloc allocation hotspots, per-variable deep sizes, and growth-since-baseline for leak spotting.
• asyncio event loop — times every loop callback and flags the coroutines that block the loop, split into CPU vs. wait.
• Flame graph — a time-proportional call tree, click to zoom.
• 3D call flow — an animated force-directed graph of the call structure with blips streaming along the live call path.
• File communication graph — which file calls into which, with live call blips between files.
• Export — download any run as a JSON report.

Works on a single file or an entire project (auto-detects the project root via .git / pyproject.toml / package layout and profiles every local .py under it).

---

Quick start

git clone <this-repo> glassbox && cd glassbox
./setup.sh
.venv/bin/python app.py

Then open http://localhost:7000, browse to a Python file, pick file or project scope, and hit run.

To try it immediately, point it at the bundled demo sample_project/main.py in project scope — an async pipeline that fetches Wikipedia and GitHub data, indexes and analyses it, and deliberately exercises every panel (network wait, CPU hotspots, memory growth, deep recursion, and an asyncio loop blocker).

Manual install

pip install -r requirements.txt
python app.py

Requires Python 3.10+. Frontend libraries (socket.io, highlight.js, three.js, 3d-force-graph) load from a CDN, so no build step or npm is needed.

---

Docker

docker build -t glassbox .
docker run -p 7000:7000 -v /path/to/your/project:/work glassbox

Then browse to /work inside the picker to reach your mounted project.

---

How it works

• Timing — sys.setprofile records call/return events (far cheaper than settrace), timing each function with both perf_counter (wall) and thread_time (CPU); the difference is wait time.
• Line heat — a background thread samples sys._current_frames() every few milliseconds, so the hot-line view is statistical and stays out of the hot path.
• Memory — tracemalloc supplies allocation hotspots and growth; variable sizes use a bounded deep-sizeof.
• asyncio — asyncio.events.Handle._run is wrapped to time every loop callback; long ones are attributed to the coroutine blocking the loop.
• Streaming — a background task pushes telemetry frames over Flask-SocketIO; heavy analysis runs off the emit path to keep the stream smooth.

Everything runs in-process, so glassbox sees your real objects and frames — at the cost of running untrusted code in its own process. Only profile code you trust.

---

Mirrors: SuperNETs • GitHub • GitLab • Codeberg