Metadata-Version: 2.4
Name: trace-util
Version: 0.2.0
Summary: Upload PyTorch profiler traces to a Hugging Face bucket and get shareable Perfetto UI links.
Project-URL: Homepage, https://github.com/ariG23498/trace-util
Project-URL: Repository, https://github.com/ariG23498/trace-util
Project-URL: Issues, https://github.com/ariG23498/trace-util/issues
Author-email: Aritra Roy Gosthipaty <aritra@huggingface.co>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: huggingface,perfetto,profiler,profiling,pytorch,traces
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.12
Requires-Dist: huggingface-hub>=1.20.1
Requires-Dist: rich>=15.0.0
Description-Content-Type: text/markdown

# trace-util

Upload your PyTorch profiler traces to a [Hugging Face bucket](https://huggingface.co/docs/huggingface_hub)
and get back ready-to-open [Perfetto UI](https://ui.perfetto.dev) 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

```bash
# 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:

```bash
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:

```python
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](https://docs.astral.sh/uv/).

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

## License

[Apache-2.0](LICENSE)
