profinspect 0.1.0

Tool to visualize profiling data -- a UI for gprof2dot

Profinspect

A local web app for visualizing profiling data. Wraps gprof2dot and Graphviz dot with an interactive browser UI featuring pan/zoom, configurable thresholds, and format selection.

Requirements

• Python 3.12+
• Graphviz (dot command must be available)
• gprof2dot (defaults to running via uvx gprof2dot)

Installation

pip install -e .

Or with uv:

uv sync

Usage

profinspect [file] [--port PORT] [--no-browser]

Run with no arguments to open the UI with an empty file input:

profinspect

Pass a profile file to open the UI and immediately render the graph:

profinspect output.pstats
profinspect --port 8080 callgrind.out

The --no-browser flag starts the server without opening a browser window.

You can also run as a module:

python -m profinspect output.pstats

Supported Profile Formats

prof, pstats, callgrind, perf, collapse, axe, dtrace, hprof, json, sleepy, sysprof, xperf

The format is auto-detected from the file extension when possible (e.g. .pstats, .prof, callgrind.out.*). If it cannot be inferred, the configured default is used. You can always override the format manually in the dropdown.

These correspond to the formats supported by gprof2dot. Common examples:

Profiler	Format	Example
Python cProfile / profile	pstats	python -m cProfile -o out.pstats script.py
Linux perf	perf	perf record -g -- ./app && perf script
Valgrind callgrind	callgrind	valgrind --tool=callgrind ./app
gprof	prof	gprof ./app gmon.out
FlameGraph / py-spy	collapse	py-spy record -f raw -o out.collapse

UI Overview

The main view has a collapsible sidebar with options and a pannable/zoomable SVG display area.

Sidebar options:

• File picker (browse button) with auto-detected format
• Format dropdown with auto-detect or manual override
• Node and edge threshold sliders (prune low-impact nodes/edges)
• Colormap selection (color, bw, gray, pink, print)
• Checkboxes: strip C++ names, wrap labels, color by self time, show samples
• Advanced: root/leaf function filters, max depth, color skew, path filter

Zoom controls: buttons for zoom in/out, 1:1 reset, and fit-to-view. Mouse wheel zooms at cursor. Click-drag to pan. Ctrl+Enter triggers generation.

Text selection: click-drag on text within graph nodes to select and copy function names. Panning is disabled over text elements to allow selection.

Settings

Accessible from the Settings tab in the UI. Persisted to ~/.config/profinspect/settings.json.

Configurable values:

• gprof2dot_command -- command to run gprof2dot (default: uvx gprof2dot)
• dot_command -- command to run Graphviz dot (default: dot)
• Default values for all generation options (format, thresholds, colormap, etc.)