trace-util 0.2.0

Upload PyTorch profiler traces to a Hugging Face bucket and get shareable Perfetto UI links.

trace-util

Upload your PyTorch profiler traces to a Hugging Face bucket and get back ready-to-open Perfetto UI links — printed straight to your terminal.

## Perfetto URLs ##
  0 aritra/aritra.json
    https://ui.perfetto.dev/#!/?url=https://huggingface.co/.../resolve/aritra/aritra.json
  1 something/something.json
    https://ui.perfetto.dev/#!/?url=https://huggingface.co/.../resolve/something/something.json

Install

# one-off run, no install (recommended)
uvx trace-util -b my-bucket -f ./traces

# or install into your environment
pip install trace-util
uv pip install trace-util

Usage

1. From the command line (recommended)

After running a PyTorch profiler and dumping the traces into a folder:

uvx trace-util -b my-bucket -f ./traces

Flag	Description
-b, --bucket-name	Name of the Hugging Face bucket to sync to (created if missing). Required.
-f, --folder-path	Local folder containing the traces. Required.
--token	Hugging Face token. Defaults to a cached / interactive login.
--no-delete	Keep files already in the bucket that are not present locally (do not mirror).
--no-color	Disable colored output (the NO_COLOR env var is also honored).

You can also run it as a module: python -m trace_util -b my-bucket -f ./traces.

2. Programmatically

The upload logic lives in trace_util.core.upload_traces, which returns the data instead of printing it — drop it into your own profiling scripts:

from trace_util import upload_traces

links = upload_traces(
    bucket_name="my-bucket",
    folder_path="./traces",
    delete=True,        # mirror the folder exactly
    do_login=False,     # skip login if HF_TOKEN is already set in the env
)

for link in links:
    print(link.path, "->", link.perfetto_url)

upload_traces returns a list of TraceLink(path, perfetto_url) named tuples. If you only want the URL formatting, use trace_util.format_perfetto_url.

How it works

1. Authenticate with the Hugging Face Hub.
2. Create the bucket (exist_ok=True, so re-runs are fine).
3. sync_bucket your local folder into the bucket.
4. List the bucket tree and turn every file into a Perfetto ?url= link.

Note: Perfetto fetches the trace from the URL in your browser, so the bucket files need to be reachable by Perfetto. The links print as plain text so they stay copy/curl-able on any terminal.

Development

This project uses uv.

uv sync                 # create the environment
uv run trace-util --help
uv build                # build the sdist + wheel into dist/

License

Apache-2.0