Skip to content

Commit 7a9de8f

Browse files
FindHaometa-codesync[bot]
authored andcommitted
Add Reproducer & Debugging Tools section to README.md (#161)
Summary: This update enhances the README.md by introducing a new section on Reproducer & Debugging Tools. Key features include: - Standalone Script Generation for extracting kernels into self-contained Python scripts. - Tensor Data Reconstruction to preserve actual tensor data or use statistical approximations. - Custom Templates for flexible reproducer workflows. - Bug Isolation to facilitate sharing reproducible test cases for debugging. Additionally, the Usage Guide link has been updated to reflect the new content. This change aims to improve user understanding and accessibility of debugging tools within TritonParse. Pull Request resolved: #161 Reviewed By: xuzhao9 Differential Revision: D84164346 Pulled By: FindHao fbshipit-source-id: 2a6ec83cbfb3a927b9ed7c3d79b14d6f03e16ab0
1 parent 47b213f commit 7a9de8f

File tree

1 file changed

+42
-2
lines changed

1 file changed

+42
-2
lines changed

README.md

Lines changed: 42 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -16,13 +16,18 @@
1616
- **📝 Multi-format IR Support** - View TTGIR, TTIR, LLIR, PTX, and AMDGCN
1717
- **🎯 Interactive Code Views** - Click-to-highlight corresponding lines across IR stages
1818

19+
### 🔧 Reproducer & Debugging Tools
20+
- **🔄 Standalone Script Generation** - Extract any kernel into a self-contained Python script
21+
- **💾 Tensor Data Reconstruction** - Preserve actual tensor data or use statistical approximation
22+
- **🎯 Custom Templates** - Flexible reproducer templates for different workflows
23+
- **🐛 Bug Isolation** - Share reproducible test cases for debugging and collaboration
24+
1925
### 📊 Structured Logging & Analysis
2026
- **📝 Compilation & Launch Tracing** - Capture detailed events with source mapping
2127
- **🔍 Stack Trace Integration** - Full Python stack traces for debugging
2228
- **📈 Metadata Extraction** - Comprehensive kernel statistics
2329

2430
### 🛠️ Developer Tools
25-
- **🔧 Reproducer Generation** - Generate standalone Python scripts to reproduce kernels
2631
- **🌐 Browser-based Interface** - No installation required, works in your browser
2732
- **🔒 Privacy-first** - All processing happens locally, no data uploaded
2833

@@ -69,6 +74,41 @@ tritonparse.utils.unified_parse("./logs/", out="./parsed_output")
6974

7075
> **🔒 Privacy Note**: Your trace files are processed entirely in your browser - nothing is uploaded to any server!
7176
77+
### 3. Generate Reproducers (Optional)
78+
79+
Extract any kernel into a standalone, executable Python script for debugging or testing:
80+
81+
```bash
82+
# Generate reproducer from first launch event
83+
tritonparse reproduce ./parsed_output/trace.ndjson.gz --line 2 --out-dir repro_output
84+
85+
# Run the generated reproducer
86+
cd repro_output/<kernel_name>/
87+
python repro_*.py
88+
```
89+
90+
**Python API:**
91+
```python
92+
from tritonparse.reproducer.orchestrator import reproduce
93+
94+
result = reproduce(
95+
input_path="./parsed_output/trace.ndjson.gz",
96+
line_index=1, # Which launch event (1-based)
97+
out_dir="repro_output"
98+
)
99+
```
100+
101+
<details>
102+
<summary>🎯 Common Reproducer Use Cases (click to expand)</summary>
103+
104+
- **🐛 Bug Isolation**: Extract a failing kernel into a minimal standalone script
105+
- **⚡ Performance Testing**: Benchmark specific kernels without running the full application
106+
- **🤝 Team Collaboration**: Share reproducible test cases with colleagues or in bug reports
107+
- **📊 Regression Testing**: Compare kernel behavior and performance across different versions
108+
- **🔍 Deep Debugging**: Modify and experiment with kernel parameters in isolation
109+
110+
</details>
111+
72112
## 🛠️ Installation
73113

74114
**For basic usage (trace generation):**
@@ -99,7 +139,7 @@ pip install triton
99139
|----------|-------------|
100140
| **[🏠 Wiki Home](https://github.com/meta-pytorch/tritonparse/wiki)** | Complete documentation and quick navigation |
101141
| **[📦 Installation](https://github.com/meta-pytorch/tritonparse/wiki/01.-Installation)** | Setup guide for all scenarios |
102-
| **[📋 Usage Guide](https://github.com/meta-pytorch/tritonparse/wiki/02.-Usage-Guide)** | Complete workflow, examples, and reproducer |
142+
| **[📋 Usage Guide](https://github.com/meta-pytorch/tritonparse/wiki/02.-Usage-Guide)** | Complete workflow, reproducer generation, and examples |
103143
| **[🌐 Web Interface](https://github.com/meta-pytorch/tritonparse/wiki/03.-Web-Interface-Guide)** | Master the visualization interface |
104144
| **[🔧 Developer Guide](https://github.com/meta-pytorch/tritonparse/wiki/04.-Developer-Guide)** | Contributing and architecture overview |
105145
| **[📝 Code Formatting](https://github.com/meta-pytorch/tritonparse/wiki/05.-Code-Formatting)** | Formatting standards and tools |

0 commit comments

Comments
 (0)