Contributing to TraceLens

Thanks for your interest in improving TraceLens — a toolkit that parses PyTorch/JAX profiler traces and generates useful insights.

---

📋 Before You Start

⚠️ NOTE FOR AMDers:

This is a public repository. Do NOT add any private, confidential, or customer-related data, code, or information to this repo.

Please ensure all contributions are free of sensitive or proprietary content before submitting.

• Read the README to understand scope and architecture.
• Search existing issues and discussions to avoid duplicates.
• For new features and enhancements (new analyser, backend integration, refactor), open an issue first to align on approach.
• Prefer small, modular, focused PRs.
• Have a ready-made utility? If your utility is already developed, you can raise a PR to add it directly to examples/custom_workflows/. This lets the community start using it right away while we plan a tighter integration into the core library.

---

Table of Contents

• Dev Setup
• Project Structure (high level)
• Code Formatting with Black
  • Installing Black
  • Using Black
• Branch Naming Convention
  • Types (type)
  • Scope (optional)
  • Examples
• Commit Message Convention
• Updating Reference Outputs

---

Dev Setup

# clone
git clone https://github.com/AMD-AGI/TraceLens.git

# optional: virtual env
python3 -m venv .venv
source .venv/bin/activate

# install (editable) + dev extras
pip install -U pip
pip install -e .[dev]

Project Structure (high level)

TraceLens/
├── TraceLens/
│   ├── Reporting/        # CLI tools for quick start utils
│   ├── Trace2Tree/       # Trace2Tree parses trace into tree data structure
│   ├── PerfModel/        # Op meta data parsing and performance modelling code (roofline, FLOPs/Byte, etc.)
│   ├── TreePerf/         # TreePerf uses Trace Tree and PerfModel to generate perf breakdowns and perf metrics TFLOPS/s, etc. 
|   |                     # This directory also contains GPUEventAnalyzer
│   ├── NcclAnalyser/     # Analysis of collective communications
│   ├── TraceFusion/      # Merging of multi‑rank traces into a global view
│   ├── TraceDiff/        # TraceDiff uses the Trace Tree format and does morphological comparison across traces
│   └── EventReplay/      # Extracts meta data and replays almost arbitrary operations
├── docs/               # tool-specific guides
├── examples/           # example traces, notebooks, scripts, custom-workflows
├── tests/              # unit & integration tests
└── setup.py

Code Formatting with Black

This project uses Black to automatically format Python code for consistency and readability.

Installing Black

You can install Black using pip:

pip install black

Using Black

To format all Python files in the project, run:

black .

You can also format a specific file:

black path/to/your_file.py

Please ensure your code is formatted with Black before submitting a pull request.

Branch Naming Convention

Please follow this branch naming convention for all feature and bug fix branches:

<type>/<scope>/<short-description>

Types (type)

Type	Purpose
feat	New feature or functionality
fix	Bug fix
docs	Documentation update
refactor	Code refactoring (no functionality change)
test	Tests and test-related changes
chore	Miscellaneous changes (e.g., build scripts)
ci	Continuous integration-related changes

Scope (optional)

The scope can be used to specify which part of the project is affected, for example: trace2tree, perfmodel, tracediff, docs, tests.

Examples

feat/perfmodel/aiter-fav3
fix/tracediff/diff-reporting-bug
docs/update-jax-docs
refactor/trace2tree/remove-dead-code
ci/add-linting-automation

Commit Message Convention

We follow Conventional Commits for commit messages. Example:

feat(perfmodel): add perf model for aiter fav3
fix(tracediff): resolve diff reporting error
docs(readme-tracediff): add docs for jax tracediff

This format helps us to automatically generate changelogs and provide more clarity in versioning.

Updating Reference Outputs

Several regression tests compare freshly generated CSV outputs against checked-in reference CSVs. When an intentional code change legitimately alters those outputs, you can refresh the references in-place by passing the --update-references flag to pytest:

python -m pytest tests/test_perf_report_regression.py --update-references

⚠️ Important: When you use --update-references in a PR, explicitly note in your PR description which reference files were updated and why.

Do not use this flag to paper over unexpected differences. If a test starts failing, first investigate why the output changed. Only refresh references once you have confirmed the new output is intentionally correct (e.g. a deliberate metric formula change, a new column, or a bug fix in the reporting pipeline).