vor-profile 0.2.0

Headless profiling capture for Python: per-step metrics + flame scopes to a .vor stream, read back with the Rust vor tooling.

vor

Python capture for the vor profiler. Instrument a training or inference loop, write per-step metrics (and optional flame frames) to a .vor file, and view it with the Rust vor tools.

Install

uv add vor-profile      # or: pip install vor-profile

The distribution is vor-profile (the name vor is taken on PyPI); the import is vor.

Usage

import vor

vor.enable()
vor.record_metric_unit("throughput", "tok/s")  # optional, once

@vor.profile
def train_step(batch):
    ...

for batch in loader:
    loss = train_step(batch)
    vor.record_metric("loss", loss)
    vor.frame_mark()
vor.flush()

Set VOR_RECORD to capture; leave it unset and nothing is written:

VOR_RECORD=/scratch/run.vor python train.py

VOR_RECORD_FLAME=1 also records flame frames (VOR_RECORD_EVERY=N samples 1 step in N). See examples/train.py.

API

• enable() - turn collection on; arm capture when VOR_RECORD is set.
• frame_mark() - end a step; writes one record.
• record_metric(name, value) - a named scalar for this step.
• record_metric_unit(name, unit) - label a metric's row, once.
• flush() - write buffered records before exit.
• @profile - flame scope per call, named module.qualname.
• profile_scope(name) - flame scope for a with block.

Viewing a capture

Reading and replaying .vor files live in the Rust crate. From a clone:

cargo run --example replay --features viz,mac -- /scratch/run.vor  # GUI panel
cargo run --example headless -- /scratch/run.vor                   # text summary

Build from source

Needs maturin. The base build is portable (metrics only); add a platform feature for GPU rows:

maturin develop                        # metrics
maturin develop --features mac         # + Apple Silicon GPU (IOKit)
maturin build --release --features cuda  # + NVIDIA GPU (NVML)