Skip to content

Commit 64937b0

Browse files
FindHaofacebook-github-bot
FindHao
authored and
facebook-github-bot
committed
Add wiki pages update readme (#29)
Summary: Enhance documentation and user guides for TritonParse - Updated README.md to improve clarity and structure, emphasizing key features and quick start instructions. - Added comprehensive installation, usage, and web interface guides in the wiki, covering various scenarios for users and developers. - Included troubleshooting tips and frequently asked questions to assist users in resolving common issues. These changes aim to provide better guidance for users and contributors, enhancing the overall experience with TritonParse. the markdown files in wiki-pages are backups for actual wiki pages. Pull Request resolved: #29 Reviewed By: Sibylau Differential Revision: D78130631 Pulled By: FindHao fbshipit-source-id: ce25f6e9fdbbcf61f49f2be6d3b041957a58db14
1 parent affc3a3 commit 64937b0

File tree

9 files changed

+2825
-258
lines changed

9 files changed

+2825
-258
lines changed

‎README.md‎

Lines changed: 71 additions & 256 deletions
Original file line numberDiff line numberDiff line change
@@ -3,301 +3,116 @@
33
[![License: BSD-3](https://img.shields.io/badge/License-BSD--3-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)
44
[![GitHub Pages](https://img.shields.io/badge/GitHub%20Pages-Deploy-brightgreen)](https://pytorch-labs.github.io/tritonparse/)
55

6-
A comprehensive visualization and analysis tool for Triton IR files, designed to help developers analyze, debug, and understand Triton kernel compilation processes.
6+
**A comprehensive visualization and analysis tool for Triton IR files** — helping developers analyze, debug, and understand Triton kernel compilation processes.
77

8-
## 🚀 Features
8+
🌐 **[Try it online →](https://pytorch-labs.github.io/tritonparse/)**
99

10-
### Visualization & Analysis
10+
## ✨ Key Features
1111

12-
- **Interactive Kernel Explorer**: Display detailed kernel information and stack traces
13-
- **Multi-format IR Support**: View and explore multiple Triton IR formats:
14-
- TTGIR (Triton GPU IR)
15-
- TTIR (Triton IR)
16-
- LLIR (LLVM IR)
17-
- PTX (NVIDIA)
18-
- AMDGCN (AMD)
19-
- **Side-by-side Comparison**: Compare the above IR code with synchronized highlighting
20-
- **Interactive Code Views**: Click-to-highlight corresponding lines across different formats
12+
- **🔍 Interactive Visualization** - Explore Triton kernels with detailed metadata and stack traces
13+
- **📊 Multi-format IR Support** - View TTGIR, TTIR, LLIR, PTX, and AMDGCN in one place
14+
- **🔄 Side-by-side Comparison** - Compare IR stages with synchronized highlighting
15+
- **📝 Structured Logging** - Capture detailed compilation events with source mapping
16+
- **🌐 Ready-to-use Interface** - No installation required, works in your browser
17+
- **🔒 Privacy-first** - All processing happens locally in your browser, no data uploaded
2118

22-
### Structured Logging
19+
## 🚀 Quick Start
2320

24-
- **Compilation Tracing**: Capture detailed Triton compilation events
25-
- **Stack Trace Integration**: Full Python stack traces for compilation events
26-
- **Metadata Extraction**: Comprehensive kernel metadata and compilation statistics
27-
- **NDJSON Output**: Structured logging format for easy processing
28-
29-
### Website Deployment Options
30-
31-
- **GitHub Pages**: Automatic deployment with GitHub Actions
32-
- **Local Development**: Full development environment setup
33-
34-
## 🛠️ Tech Stack
35-
36-
**Frontend:**
37-
38-
- React 19 with TypeScript
39-
- Vite for build tooling
40-
- Tailwind CSS for styling
41-
- Monaco Editor for code display
42-
- React Syntax Highlighter for syntax highlighting
43-
- React Resizable Panels for layout
44-
45-
**Backend/Processing:**
46-
47-
- Python with Triton integration
48-
- Structured logging and event tracing
49-
- Source mapping extraction utilities
50-
51-
## 📦 Installation
52-
53-
### For Users (Trace Generation Only)
54-
55-
**Prerequisites:**
56-
57-
- **Python** >= 3.9
58-
- **Triton** > 3.3.1
59-
60-
For now, you need to [manually compile latest Triton from source](https://github.com/triton-lang/triton?tab=readme-ov-file#install-from-source).
61-
62-
**Quick Start:**
63-
64-
```bash
65-
# Clone the repository
66-
git clone https://github.com/pytorch-labs/tritonparse.git
67-
cd tritonparse
68-
69-
# Install Python dependencies
70-
pip install -e .
71-
```
72-
73-
### For Website Developers (Optional)
74-
75-
**Additional Prerequisites:**
76-
77-
- **Node.js** >= 18.0.0
78-
- **npm**
79-
80-
**Website Setup:**
81-
82-
```bash
83-
# Install website dependencies
84-
cd website
85-
npm install
86-
```
87-
88-
## 🎯 Usage
89-
90-
### 1. Generate Triton Trace Files
91-
92-
Please refer to [wiki usage](https://github.com/pytorch-labs/tritonparse/wiki/Usage) for more details.
93-
94-
First, integrate TritonParse with your Triton/PyTorch code to generate trace files:
21+
### 1. Generate Traces
9522

9623
```python
97-
import torch
98-
# === TritonParse init ===
9924
import tritonparse.structured_logging
100-
# Initialize structured logging to capture Triton compilation events
101-
# This will generate NDJSON trace logs in ./logs/
102-
log_path = "./logs/"
103-
tritonparse.structured_logging.init(log_path)
104-
# === TritonParse init end ===
10525

106-
# The below is your original Triton/PyTorch 2 code
107-
...
26+
# Initialize logging
27+
tritonparse.structured_logging.init("./logs/")
10828

109-
# === TritonParse parse ===
29+
# Your Triton/PyTorch code here
30+
# ... your kernels ...
31+
32+
# Parse and generate trace files
11033
import tritonparse.utils
111-
tritonparse.utils.unified_parse(log_path)
112-
# === TritonParse parse end ===
34+
tritonparse.utils.unified_parse("./logs/")
11335
```
114-
See a full example in [`tests/test_add.py`](https://github.com/pytorch-labs/tritonparse/blob/main/tests/test_add.py).
115-
116-
Exampled output:
117-
```bash
118-
% TORCHINDUCTOR_FX_GRAPH_CACHE=0 python test_add.py
119-
Triton kernel executed successfully
120-
Torch compiled function executed successfully
121-
WARNING:SourceMapping:No frame_id or frame_compile_id found in the payload.
122-
WARNING:SourceMapping:No frame_id or frame_compile_id found in the payload.
123-
tritonparse log file list: /tmp/tmpl1tp9fto/log_file_list.json
36+
The example terminal output is:
37+
```bash
38+
tritonparse log file list: /tmp/tmp1gan7zky/log_file_list.json
39+
INFO:tritonparse:Copying parsed logs from /tmp/tmp1gan7zky to /scratch/findhao/tritonparse/tests/parsed_output
40+
41+
================================================================================
42+
📁 TRITONPARSE PARSING RESULTS
43+
================================================================================
44+
📂 Parsed files directory: /scratch/findhao/tritonparse/tests/parsed_output
45+
📊 Total files generated: 2
46+
47+
📄 Generated files:
48+
--------------------------------------------------
49+
1. 📝 dedicated_log_triton_trace_findhao__mapped.ndjson.gz (7.2KB)
50+
2. 📝 log_file_list.json (181B)
51+
================================================================================
52+
✅ Parsing completed successfully!
53+
================================================================================
12454
```
125-
In our test example, it has two triton kernels: one is a pure triton kernel and the other is a PT2 compiled triton kernel. `TORCHINDUCTOR_FX_GRAPH_CACHE=0 ` is used to disable FX graph cache to let PT2 compiler compile the kernel every time. Otherwise, the final parsed log files will only contain the first triton kernel.
126-
The final parsed gz files are stored in the `/tmp/tmpl1tp9fto/` directory. The `./logs` directory contains the raw NDJSON logs without source code mapping.
127-
128-
### 2. Analyze with Web Interface
129-
130-
#### Option A: Online Interface (Recommended)
131-
132-
**Visit [https://pytorch-labs.github.io/tritonparse/](https://pytorch-labs.github.io/tritonparse/)** to use the tool directly in your browser:
133-
134-
1. **Open your local trace file** (NDJSON or .gz format) directly in the browser
135-
2. **Explore the visualization** using the Overview and Code Comparison tabs
136-
137-
**Supported File Formats:**
138-
- `.ndjson` - Newline Delimited JSON trace files
139-
- `.gz` - Gzip compressed trace files
140-
141-
#### Interface Overview
142-
143-
Once you load a trace file, you'll see the main interface with several key components:
14455

145-
**Kernel Overview & Details:**
56+
### 2. Visualize Results
14657

147-
![Kernel Overview](docs/screenshots/kernel-overview.png)
58+
**Visit [https://pytorch-labs.github.io/tritonparse/](https://pytorch-labs.github.io/tritonparse/)** and open your local trace files (.ndjson.gz format).
14859

149-
*The main interface showing the kernel list, compilation metadata, call stack, and navigation links to different IR representations.*
60+
> **🔒 Privacy Note**: Your trace files are processed entirely in your browser - nothing is uploaded to any server!
15061
151-
**Code Comparison View:**
152-
153-
![Code Comparison](docs/screenshots/code-comparison.png)
154-
155-
*Side-by-side comparison of different IR stages (e.g., TTGIR and PTX) with synchronized line highlighting and interactive navigation.*
156-
157-
#### Option B: Local Development (For Contributors)
158-
159-
For contributors working on the website:
160-
161-
```bash
162-
cd website
163-
npm install
164-
npm run dev
165-
```
166-
167-
Access the application at `http://localhost:5173`
168-
169-
**Available Scripts:**
170-
171-
- `npm run build` - Standard build
172-
- `npm run build:single` - Standalone HTML file
173-
- `npm run preview` - Preview production build
174-
175-
## 📁 Project Structure
176-
177-
```
178-
tritonparse/
179-
├── tritonparse/ # Python package
180-
│ ├── structured_logging.py # Main logging infrastructure
181-
│ ├── extract_source_mappings.py # Source mapping utilities
182-
│ ├── source_type.py # Source type definitions
183-
│ ├── utils.py # Helper utilities
184-
│ ├── common.py # Common functions
185-
│ └── tp_logger.py # Logger configuration
186-
├── website/ # React web application
187-
│ ├── src/ # React source code
188-
│ ├── public/ # Static assets and example files
189-
│ ├── scripts/ # Build utilities (inline-html.js)
190-
│ ├── node_modules/ # Dependencies
191-
│ ├── package.json # Node.js dependencies
192-
│ ├── vite.config.ts # Vite configuration
193-
│ └── dist/ # Built application (after build)
194-
├── docs/ # Documentation and assets
195-
│ ├── README.md # Documentation guidelines
196-
│ └── screenshots/ # Screenshots for README
197-
├── tests/ # Test files and example traces
198-
│ ├── test_add.py # Example Triton kernel test
199-
│ ├── unit_tests.py # Unit tests
200-
│ └── *.ndjson # Example trace files
201-
├── run.py # Main runner script
202-
├── pyproject.toml # Python package configuration
203-
├── LICENSE # BSD-3 license
204-
├── CONTRIBUTING.md # Contribution guidelines
205-
└── CODE_OF_CONDUCT.md # Code of conduct
206-
```
207-
208-
## 🔧 Development
209-
210-
### Python Development
211-
212-
**Install in development mode:**
62+
## 🛠️ Installation
21363

64+
**For basic usage (trace generation):**
21465
```bash
66+
git clone https://github.com/pytorch-labs/tritonparse.git
67+
cd tritonparse
21568
pip install -e .
21669
```
21770

218-
**Example test:**
71+
**Prerequisites:** Python ≥ 3.10, Triton > 3.3.1 ([install from source](https://github.com/triton-lang/triton)), GPU required (NVIDIA/AMD)
21972

220-
```bash
221-
cd tests
222-
python test_add.py
223-
```
73+
## 📚 Complete Documentation
22474

225-
### Environment Variables
75+
| 📖 Guide | Description |
76+
|----------|-------------|
77+
| **[🏠 Wiki Home](https://github.com/pytorch-labs/tritonparse/wiki)** | Complete documentation and navigation |
78+
| **[📦 Installation Guide](https://github.com/pytorch-labs/tritonparse/wiki/01.-Installation)** | Detailed setup for all scenarios |
79+
| **[📋 Usage Guide](https://github.com/pytorch-labs/tritonparse/wiki/02.-Usage-Guide)** | Complete workflow and examples |
80+
| **[🌐 Web Interface Guide](https://github.com/pytorch-labs/tritonparse/wiki/03.-Web-Interface-Guide)** | Master the visualization interface |
81+
| **[🔧 Developer Guide](https://github.com/pytorch-labs/tritonparse/wiki/04.-Developer-Guide)** | Contributing and development setup |
82+
| **[❓ FAQ](https://github.com/pytorch-labs/tritonparse/wiki/06.-FAQ)** | Frequently asked questions |
22683

227-
- `TRITONPARSE_DEBUG=1` - Enable debug logging
228-
- `TRITONPARSE_NDJSON=1` - Output in NDJSON format (default)
229-
230-
### Website Development (For Contributors)
231-
232-
**Start development server:**
233-
234-
```bash
235-
cd website
236-
npm run dev
237-
```
238-
239-
**Available Scripts:**
240-
241-
- `npm run dev` - Start development server
242-
- `npm run build` - Production build
243-
- `npm run build:single` - Standalone HTML build
244-
- `npm run lint` - Run ESLint
245-
- `npm run preview` - Preview production build
246-
247-
## 🚀 Deployment
248-
249-
### Live Website
250-
251-
The TritonParse visualization tool is automatically deployed and available at:
252-
**[https://pytorch-labs.github.io/tritonparse/](https://pytorch-labs.github.io/tritonparse/)**
253-
254-
### For Contributors: Local Deployment
255-
256-
**Build standalone version:**
257-
258-
```bash
259-
cd website
260-
npm run build:single
261-
```
84+
## 🛠️ Tech Stack
26285

263-
The `dist/standalone.html` file contains the entire application and can be deployed anywhere.
86+
- **Frontend**: React 19, TypeScript, Vite, Tailwind CSS, Monaco Editor
87+
- **Backend**: Python with Triton integration, structured logging
88+
- **Deployment**: GitHub Pages, automatic deployment
26489

26590
## 📊 Understanding Triton Compilation
26691

267-
TritonParse helps visualize the Triton compilation pipeline:
92+
TritonParse visualizes the complete Triton compilation pipeline:
26893

269-
1. **Python Source** → Triton kernel functions
270-
2. **TTIR** → Triton's high-level IR
271-
3. **TTGIR** → GPU-specific Triton IR
272-
4. **LLIR** → LLVM IR representation
273-
5. **PTX** → NVIDIA PTX assembly
274-
6. **AMDGCN** → AMD GPU IR
94+
**Python Source** → **TTIR** → **TTGIR** → **LLIR** → **PTX/AMDGCN**
27595

27696
Each stage can be inspected and compared to understand optimization transformations.
27797

27898
## 🤝 Contributing
27999

280-
1. Fork the repository
281-
2. Create a feature branch: `git checkout -b feature-name`
282-
3. Make your changes
283-
4. Run tests: `npm test` (website) and `python -m pytest` (Python)
284-
5. Submit a pull request
285-
286-
## 📝 License
100+
We welcome contributions! Please see our **[Developer Guide](https://github.com/pytorch-labs/tritonparse/wiki/04.-Developer-Guide)** for:
101+
- Development setup
102+
- Code formatting standards
103+
- Pull request process
104+
- Architecture overview
287105

288-
This project is licensed under the BSD-3 License - see the [LICENSE](LICENSE) file for details.
106+
## 📞 Support & Community
289107

290-
## 🔗 Related Projects
108+
- **🐛 Report Issues**: [GitHub Issues](https://github.com/pytorch-labs/tritonparse/issues)
109+
- **💬 Discussions**: [GitHub Discussions](https://github.com/pytorch-labs/tritonparse/discussions)
110+
- **📚 Documentation**: [TritonParse Wiki](https://github.com/pytorch-labs/tritonparse/wiki)
291111

292-
- [OpenAI Triton](https://github.com/openai/triton) - The Triton compiler and language
293-
- [PyTorch](https://pytorch.org/) - Deep learning framework with Triton integration
112+
## 📄 License
294113

295-
## 📞 Support
296-
297-
- **Issues**: [GitHub Issues](https://github.com/pytorch-labs/tritonparse/issues)
298-
- **Discussions**: [GitHub Discussions](https://github.com/pytorch-labs/tritonparse/discussions)
299-
- **Wiki**: [TritonParse Wiki](https://github.com/pytorch-labs/tritonparse/wiki)
114+
This project is licensed under the BSD-3 License - see the [LICENSE](LICENSE) file for details.
300115

301116
---
302117

303-
**Note**: This tool is designed for developers working with Triton kernels and GPU computing. Basic familiarity with CUDA, GPU programming concepts, and the Triton language is recommended for effective use.
118+
**✨ Ready to get started?** Visit our **[Installation Guide](https://github.com/pytorch-labs/tritonparse/wiki/01.-Installation)** or try the **[online tool](https://pytorch-labs.github.io/tritonparse/)** directly!

0 commit comments

Comments
 (0)