|
3 | 3 | [](https://opensource.org/licenses/BSD-3-Clause)
|
4 | 4 | [](https://pytorch-labs.github.io/tritonparse/)
|
5 | 5 |
|
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. |
7 | 7 |
|
8 |
| -## 🚀 Features |
| 8 | +🌐 **[Try it online →](https://pytorch-labs.github.io/tritonparse/)** |
9 | 9 |
|
10 |
| -### Visualization & Analysis |
| 10 | +## ✨ Key Features |
11 | 11 |
|
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 |
21 | 18 |
|
22 |
| -### Structured Logging |
| 19 | +## 🚀 Quick Start |
23 | 20 |
|
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 |
95 | 22 |
|
96 | 23 | ```python
|
97 |
| -import torch |
98 |
| -# === TritonParse init === |
99 | 24 | 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 === |
105 | 25 |
|
106 |
| -# The below is your original Triton/PyTorch 2 code |
107 |
| -... |
| 26 | +# Initialize logging |
| 27 | +tritonparse.structured_logging.init("./logs/") |
108 | 28 |
|
109 |
| -# === TritonParse parse === |
| 29 | +# Your Triton/PyTorch code here |
| 30 | +# ... your kernels ... |
| 31 | + |
| 32 | +# Parse and generate trace files |
110 | 33 | import tritonparse.utils
|
111 |
| -tritonparse.utils.unified_parse(log_path) |
112 |
| -# === TritonParse parse end === |
| 34 | +tritonparse.utils.unified_parse("./logs/") |
113 | 35 | ```
|
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 | +================================================================================ |
124 | 54 | ```
|
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: |
144 | 55 |
|
145 |
| -**Kernel Overview & Details:** |
| 56 | +### 2. Visualize Results |
146 | 57 |
|
147 |
| - |
| 58 | +**Visit [https://pytorch-labs.github.io/tritonparse/](https://pytorch-labs.github.io/tritonparse/)** and open your local trace files (.ndjson.gz format). |
148 | 59 |
|
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! |
150 | 61 |
|
151 |
| -**Code Comparison View:** |
152 |
| - |
153 |
| - |
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 |
213 | 63 |
|
| 64 | +**For basic usage (trace generation):** |
214 | 65 | ```bash
|
| 66 | +git clone https://github.com/pytorch-labs/tritonparse.git |
| 67 | +cd tritonparse |
215 | 68 | pip install -e .
|
216 | 69 | ```
|
217 | 70 |
|
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) |
219 | 72 |
|
220 |
| -```bash |
221 |
| -cd tests |
222 |
| -python test_add.py |
223 |
| -``` |
| 73 | +## 📚 Complete Documentation |
224 | 74 |
|
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 | |
226 | 83 |
|
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 |
262 | 85 |
|
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 |
264 | 89 |
|
265 | 90 | ## 📊 Understanding Triton Compilation
|
266 | 91 |
|
267 |
| -TritonParse helps visualize the Triton compilation pipeline: |
| 92 | +TritonParse visualizes the complete Triton compilation pipeline: |
268 | 93 |
|
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** |
275 | 95 |
|
276 | 96 | Each stage can be inspected and compared to understand optimization transformations.
|
277 | 97 |
|
278 | 98 | ## 🤝 Contributing
|
279 | 99 |
|
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 |
287 | 105 |
|
288 |
| -This project is licensed under the BSD-3 License - see the [LICENSE](LICENSE) file for details. |
| 106 | +## 📞 Support & Community |
289 | 107 |
|
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) |
291 | 111 |
|
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 |
294 | 113 |
|
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. |
300 | 115 |
|
301 | 116 | ---
|
302 | 117 |
|
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