Skip to content

03. Web Interface Guide

Jump to bottom
Yueming Hao edited this page Jul 10, 2025 · 3 revisions

This guide walks you through the TritonParse web interface, helping you effectively analyze and visualize Triton kernel compilation traces.

🌐 Accessing the Interface

Online Interface (Recommended)

Visit: https://pytorch-labs.github.io/tritonparse/

✅ Advantages:

  • Always up-to-date with latest features
  • No installation required
  • Works on any device with a browser
  • Supports all file formats

Local Development Interface

For contributors or custom deployments:

cd website
npm install
npm run dev

Access at http://localhost:5173

📂 Loading Trace Files

Supported File Formats

Format Description Source Mapping Best For
.gz Compressed parsed traces ✅ Full Production analysis
.ndjson Raw trace logs ❌ Limited Quick debugging

Loading Methods

Method 1: File Upload

  1. Click "Browse Files" or drag-and-drop files
  2. Select .gz files from your parsed_output directory
  3. The interface will automatically process and display kernels

Method 2: URL Loading

  1. Click "Load from URL"
  2. Enter the URL to your trace file
  3. Click "Load"

Method 3: URL Parameters

Direct link with parameters:

https://pytorch-labs.github.io/tritonparse/?json_url=YOUR_FILE_URL&view=ir_code_comparison&kernel_hash=KERNEL_HASH

Parameters:

  • json_url: URL to your trace file
  • view: overview or ir_code_comparison
  • kernel_hash: Specific kernel to highlight

🎯 Interface Overview

Main Navigation

The interface consists of two main tabs:

  1. 📊 Overview Tab - Kernel metadata and navigation
  2. 🔍 Comparison Tab - Side-by-side IR code comparison

Kernel Selection

  • Kernel List: Browse all kernels in the trace
  • Kernel Details: Click any kernel to view detailed information
  • Direct Navigation: Use IR links to jump to specific views

📊 Overview Tab

Kernel Information Panel

Basic Information:

  • Kernel Name: Function name and signature
  • Hash: Unique identifier for the kernel
  • Grid Size: Launch configuration (e.g., (1024,))
  • Block Size: Thread block dimensions
  • Device: Target GPU device

Compilation Metadata:

  • Compile Time: Time taken for compilation
  • Memory Usage: Shared memory, register usage
  • Optimization Flags: Compiler settings used

Call Stack Section

Python Source Context:

  • File Path: Source file that triggered compilation
  • Line Numbers: Exact location in your code
  • Function Names: Call hierarchy
  • Stack Trace: Complete compilation trigger path

Example Call Stack:

test_add.py:52 in test_tensor_add
  c_triton = tensor_add(a, b)
tensor_add.py:38 in tensor_add
  add_kernel[grid](a, b, c, n_elements, BLOCK_SIZE)

IR Navigation Links

Quick access to different IR representations:

  • 🔤 TTGIR - Triton GPU IR (high-level)
  • 🔤 TTIR - Triton IR (language-level)
  • 🔤 LLIR - LLVM IR (low-level)
  • ⚡ PTX - NVIDIA assembly
  • 🔥 AMDGCN - AMD assembly

Click any link to view the full IR code in a dedicated viewer.

Metadata Sections

Supported Data Types:

  • Lists FP8, FP16, FP32 support
  • Shows tensor type compatibility

Optimization Information:

  • Vectorization settings
  • Memory coalescing details
  • Register allocation stats

🔍 Comparison Tab

Side-by-Side View

The comparison tab shows two IR representations side-by-side:

Left Panel: Source IR (e.g., TTGIR) Right Panel: Target IR (e.g., PTX)

Interactive Features

1. Synchronized Highlighting

  • Click any line in either panel
  • Corresponding lines in the other panel will highlight
  • Color-coded mapping shows transformation relationships

2. Source Mapping

  • Line-by-line correspondence between IR stages
  • Transformation visualization shows how code changes
  • Multi-line mappings for complex transformations

3. Navigation Controls

  • Scroll synchronization (optional)
  • Line number display
  • Search functionality within code panels

IR Selection

Dropdown Menus:

  • Left Panel: Choose source IR format
  • Right Panel: Choose target IR format

Popular Combinations:

  • TTGIR ↔ PTX - High-level to assembly
  • TTIR ↔ LLIR - Language to LLVM IR
  • LLIR ↔ PTX - LLVM to assembly

Code Viewer Features

Syntax Highlighting

  • Language-specific highlighting for each IR type
  • Keywords, operators, and literals clearly distinguished
  • Comment and annotation support

Line Numbers

  • Absolute line numbers for each IR
  • Clickable lines for source mapping
  • Highlighted regions for mapped sections

Search and Navigation

  • Ctrl+F for in-panel search
  • Jump to line functionality
  • Folding support for large blocks

🛠️ Advanced Features

URL Sharing

Generate shareable links for specific views:

https://pytorch-labs.github.io/tritonparse/?json_url=YOUR_FILE&view=ir_code_comparison&kernel_hash=abc123

Keyboard Shortcuts

  • Tab: Switch between Overview and Comparison
  • Ctrl+F: Search within code panels
  • Ctrl+G: Go to line number
  • Esc: Close search/dialog boxes

Export Options

  • Copy Code: Right-click to copy IR code
  • Save View: Bookmark current analysis state
  • Screenshot: Browser screenshot for reports

🔍 Analysis Workflows

1. Performance Debugging

Goal: Identify performance bottlenecks

Steps:

  1. Load trace from your performance test
  2. Check Overview for compilation metadata
  3. Compare TTGIR → PTX to see final assembly
  4. Look for:
    • Inefficient memory patterns
    • Excessive register usage
    • Suboptimal instruction sequences

2. Optimization Verification

Goal: Verify optimization effectiveness

Steps:

  1. Load traces from before/after optimization
  2. Compare metadata (compile time, memory usage)
  3. Examine IR differences using side-by-side view
  4. Verify:
    • Vectorization improvements
    • Memory coalescing
    • Register allocation efficiency

3. Compilation Pipeline Understanding

Goal: Learn how Triton compiles kernels

Steps:

  1. Start with simple kernel trace
  2. Follow the pipeline: TTIR → TTGIR → LLIR → PTX
  3. Use source mapping to see transformations
  4. Understand:
    • How high-level operations become instructions
    • Where optimizations are applied
    • GPU-specific adaptations

4. Debugging Compilation Errors

Goal: Diagnose compilation failures

Steps:

  1. Check call stack for error location
  2. Examine TTIR for syntax issues
  3. Look at LLIR for type problems
  4. Check PTX generation for hardware compatibility

📱 Browser Compatibility

Supported Browsers

  • Chrome/Chromium 90+ (recommended)
  • Firefox 88+
  • Safari 14+
  • Edge 90+

Performance Tips

  • Use latest browser for best performance
  • Enable hardware acceleration for large files
  • Clear browser cache if experiencing issues
  • Use incognito mode for sensitive traces

File Size Limits

  • Browser dependent (typically 100MB+)
  • Gzip compression helps with large traces
  • Split large traces if needed

🐛 Interface Troubleshooting

Common Issues

1. File Won't Load

Symptoms: "Failed to load trace file" error

Solutions:

  • Ensure using .gz files from parsed_output
  • Check file isn't corrupted: zcat file.gz | head
  • Try with smaller trace file first
  • Clear browser cache and cookies

2. Missing Source Mapping

Symptoms: Click doesn't highlight corresponding lines

Solutions:

  • Use .gz files instead of .ndjson
  • Ensure parsing completed successfully
  • Check browser console for JavaScript errors

3. Slow Performance

Symptoms: Interface is sluggish or unresponsive

Solutions:

  • Use smaller trace files
  • Enable hardware acceleration in browser
  • Close other browser tabs
  • Try different browser

4. Display Issues

Symptoms: Layout problems or missing elements

Solutions:

  • Refresh the page
  • Clear browser cache
  • Try different browser
  • Check browser console for errors

Debug Mode

Enable debug logging in browser console:

// Open browser console and run:
localStorage.setItem('tritonparse-debug', 'true');
// Refresh page

🔧 Customization Options

Theme Settings

  • Dark/Light mode (respects system preference)
  • Syntax highlighting themes
  • Font size adjustment

Layout Options

  • Panel sizing (drag to resize)
  • Scroll synchronization toggle
  • Line number display options

Export Settings

  • Code formatting options
  • Include metadata in exports
  • File naming preferences

📚 Tips for Effective Analysis

1. Start with Overview

  • Always check kernel metadata first
  • Understand the compilation context
  • Note any warnings or unusual values

2. Use Source Mapping

  • Click lines to see transformations
  • Follow optimization patterns
  • Identify transformation hotspots

3. Compare Strategically

  • TTGIR → PTX: See final result
  • TTIR → TTGIR: Understand GPU adaptation
  • LLIR → PTX: Check code generation

4. Look for Patterns

  • Memory access patterns
  • Vectorization opportunities
  • Register pressure indicators

5. Document Findings

  • Take screenshots of important views
  • Note line numbers for reference
  • Share URLs with team members

🔗 Next Steps

After mastering the web interface:

  1. Practice with Basic Examples
  2. Explore Advanced Examples
  3. Learn about File Formats
  4. Check Performance Optimization guide
  5. Join GitHub Discussions

📚 Related Documentation

Clone this wiki locally