argus

Lightweight profiling and tracing for Python ML workloads.

Wrap the phases of a pipeline in spans, nest them, attach what you need to know, and export a Chrome trace you can open in Perfetto. It has no dependencies beyond Python.

Apache-2.0 · Python 3.10+ · alpha

Spans in, a trace out.

A tracer collects spans as your code runs. Each span has a name, a category and a scope, and they nest the way your calls do.

Load the exported file at ui.perfetto.dev to see the timeline.

basic_trace.py
import argus

tracer = argus.Tracer()

with tracer.span("full_pipeline", category="phase", scope="pipeline"):
    with tracer.span("preprocessing", category="compute",
                     scope="pipeline.preprocess"):
        data = list(range(1000))
    with tracer.span("inference", category="compute",
                     scope="pipeline.inference"):
        result = sum(data)

argus.export_chrome(tracer, "basic_trace.json")

Made for model code

Beyond plain spans, argus ships hooks for the place where inference time and memory actually go.

Spans
Nested, timed with a monotonic nanosecond clock, with metadata you add as you go.
Decode
trace_generate traces a PyTorch model's greedy decode: the prefill, then a span for every token.
KV cache
KVCacheTracker records the cache's size after each token as memory events on the same timeline.
Export
Chrome Trace Format, which Perfetto and chrome://tracing both read.

Install

argus installs from GitHub. The PyTorch hooks need PyTorch; the core needs nothing else.

$ pip install git+https://github.com/cottus-ai/argus

See where the time goes.

argus is Apache-2.0 and early. Issues and pull requests are welcome.