03. Web Interface Guide

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://meta-pytorch.org/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

TritonParse supports three convenient ways to load trace files:

1. File Upload (Recommended for local files)

• Click "Browse Files" or drag-and-drop .gz/.ndjson files directly
• Files are processed entirely in your browser (no upload to server)

2. URL Loading (For remote files)

• Click "Load from URL" and enter the trace file URL
• Or use URL parameters: ?json_url=YOUR_FILE_URL
• ⚠️ CORS Note: Files must allow cross-origin access, or host the website on the same domain

3. Direct URL Links (For sharing)

• Share complete analysis states via URL parameters
• Example: ?json_url=FILE&view=ir_code_view&kernel_hash=abc123
• See URL Parameters Reference for all options

🎯 Interface Overview

Main Navigation

The interface consists of three main tabs:

1. 📊 Overview Tab - Kernel metadata and navigation
2. 🔍 IR Code View Tab - Side-by-side IR code viewing
3. 🔄 File Diff Tab - Compare kernels across different trace files

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
• Tiled View Toggle: Switch between list and compact tiled view for better density

💡 New: The kernel selector now features a sticky, collapsible tiled view mode for easier navigation with many kernels.

📊 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

Launch Analysis Panel

If launch tracing was enabled (enable_trace_launch=True), a "Launch Analysis" panel will appear. This panel provides insights into how kernel launch parameters vary across multiple executions of the same kernel.

Information Displayed:

• Total Launches: The total number of times this kernel was launched.
• Varying Parameters (diffs): A table showing launch parameters (like grid_x, num_warps) that changed across different launches, along with their unique values. This is useful for understanding the impact of dynamic shapes.
• Constant Parameters (sames): A list of parameters that remained the same for all launches.
• Tensor Arguments: Concise summaries with expandable details for each tensor parameter

💡 New: Tensor arguments now display with compact summaries that can be expanded to show full details including shape, dtype, and statistical information.

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

🔍 IR Code View Tab

Side-by-Side View

The IR code view 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

The interface uses Monaco Editor (same as VS Code) for professional code viewing:

Core Features:

• Advanced syntax highlighting - Language-aware parsing for each IR type
• Line numbers and minimap - Easy orientation in large files
• Code folding - Collapse/expand code sections
• Search and find - Quick navigation within code

Interactive Features:

• Clickable line numbers - Activate source mapping to other IRs
• Highlighted regions - Show mapped code sections
• Multiple cursors - Select and analyze multiple locations
• Syntax-aware selections - Smart code selection

💡 IDE-quality code viewing with all the features you expect from modern editors.

🔄 File Diff View - Compare Kernels Across Traces

The File Diff View allows you to compare kernels from two different trace files side-by-side. This is invaluable for:

• Comparing before/after optimization changes
• Analyzing kernel evolution across code versions
• Debugging compilation differences
• Validating refactoring impacts

Accessing File Diff View

1. Via Main Navigation: Click the "File Diff" tab in the main interface
2. Via URL Parameter: https://meta-pytorch.org/tritonparse/?view=file_diff
3. Via Preview Mode: Click "Compare in File Diff" from Overview or IR Code view

Loading Files for Comparison

File Diff requires two trace files - one for each side:

• Left (Base): Your reference trace - uses json_url parameter or current loaded file
• Right (Comparison): The trace to compare - uses json_b_url parameter
• Loading: Same methods as main interface (upload, URL, or drag-and-drop)

💡 Tip: You can compare files from different sources - local file on left, URL on right, etc.

URL Parameters for File Diff

Key parameters for File Diff view:

Parameter	Description	Example
json_url	Left/base trace file	trace1.gz
json_b_url	Right/comparison trace file	trace2.gz
kernel_hash_a	Pre-select left kernel	abc123
kernel_hash_b	Pre-select right kernel	def456
mode	single or all IRs	single
ir	IR type to show	ttgir

See URL Parameters Reference for all diff options (ignore_ws, word_level, context, etc.).

Example:

?view=file_diff&json_url=old.gz&json_b_url=new.gz&mode=single&ir=ttgir

Comparison Modes

Single Mode (Default)

Compare one specific IR type at a time:

• Focused comparison of selected IR (TTGIR, TTIR, LLIR, PTX, AMDGCN, or Python source)
• Detailed diff view with syntax highlighting
• Line-by-line correspondence clearly marked
• IR selector dropdown to switch between different IRs

Use when: You want to focus on a specific compilation stage

All Mode

See all IR types diff simultaneously:

• Comprehensive overview of all IRs in one view
• Stacked layout showing each IR side-by-side
• Quick scan of changes across all stages
• Ideal for documentation or presentations

Use when: You need to see the full picture of all changes

Diff Display Options

Option	Default	Description
Ignore Whitespace	true	Ignore spaces/indentation
Word-level Diff	true	Highlight word vs line changes
Context Lines	3	Unchanged lines around changes
Word Wrap	on	Wrap vs horizontal scroll
Only Changes	false	Hide unchanged sections

Kernel Selection

Automatic Matching: Kernels are matched by hash when available

Manual Selection: Use dropdowns to select different kernels on each side

Pre-selection: Use kernel_hash_a and kernel_hash_b URL parameters

💡 Tip: You can compare different kernel implementations, not just the same kernel from different traces.

Supported IR Types

All IR types are supported: TTGIR, TTIR, LLIR, PTX (NVIDIA), AMDGCN (AMD), and Python source.

Quick Access via Preview Mode

Jump to File Diff from other tabs:

• From Overview: Click "Compare in File Diff" to switch with kernel pre-selected
• From IR Code View: Click "Compare in File Diff" to switch with current IR and kernel

💡 Preview mode remembers your selections for seamless navigation.

Common Use Cases

Optimization Validation: Compare before/after traces to verify optimizations worked as expected

Compiler Updates: Compare same code with different Triton versions to see code generation changes

Refactoring Verification: Ensure refactored code produces identical IR (any diff indicates semantic change)

Regression Debugging: Compare working vs broken versions to identify what changed

Performance Analysis: Compare different kernel implementations to understand performance differences

Diff Color Coding

The diff view uses clear color coding:

• 🟢 Green: Lines added in right file
• 🔴 Red: Lines removed from left file
• 🟡 Yellow: Lines modified (different in both files)
• ⚪ White/Gray: Unchanged lines (context)

Navigation Tips

• Adjust context lines for more/less surrounding code
• Use word-level diffs for granular change highlighting
• Enable "Only Changes" to focus on modified sections in large files
• Browser search (Ctrl+F / Cmd+F) works within diffs
• Share URLs with specific diff configurations

Important Notes

• CORS: URL-loaded files must allow cross-origin access (local uploads work without CORS)
• Performance: Use "Only Changes" mode for very large diffs
• Missing IRs: Empty side shown if IR type not available in trace
• Hash Matching: Same-hash kernels automatically paired

🛠️ Advanced Features

URL Parameters Reference

Complete list of all supported URL parameters:

Parameter	Values	Description
json_url	URL string	Main trace file to load
json_b_url	URL string	Second trace file (File Diff only)
view	overview, ir_code_view, file_diff	Which tab to show
kernel_hash	Hash string	Kernel to select (Overview/IR Code View)
kernel_hash_a	Hash string	Left kernel (File Diff)
kernel_hash_b	Hash string	Right kernel (File Diff)
mode	single, all	Single IR or all IRs (File Diff)
ir	ttgir, ttir, llir, ptx, amdgcn	Which IR to show
ignore_ws	true, false	Ignore whitespace in diff
word_level	true, false	Word-level vs line-level diff
context	Number	Context lines in diff
wrap	on, off	Word wrap in code viewer
only_changed	true, false	Show only changed lines

URL Sharing Examples

Load specific kernel in Overview:

?json_url=YOUR_FILE&view=overview&kernel_hash=abc123

Open IR Code View with specific IR:

?json_url=YOUR_FILE&view=ir_code_view&kernel_hash=abc123&ir=ttgir

Compare two traces:

?view=file_diff&json_url=old.gz&json_b_url=new.gz&mode=single&ir=ptx

Export Options

• Copy Code: Right-click to copy IR code
• Copy Button: Click the copy icon in code viewers for one-click copy
• Save View: Bookmark current analysis state
• Screenshot: Browser screenshot for reports

💡 New: Copy buttons are now available in all code viewer panels for quick code extraction.

Footer Information

The interface footer displays useful metadata:

• Version: Current TritonParse version
• Build Date: When the interface was built (localized to your timezone)
• Git Commit: Short SHA of the deployment
• Links: Quick access to documentation and GitHub

💡 New: Footer shows real-time version and build information to ensure you're using the latest features.

🔍 Analysis Workflows

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 in IR Code View to see transformations
4. Understand:
   • How high-level operations become instructions
   • Where optimizations are applied
   • GPU-specific adaptations

📱 Browser & Performance

Supported Browsers

• Chrome/Chromium 100+ (recommended for best performance)
• Firefox 100+
• Safari 14+
• Edge 100+

Performance Optimization

• Use latest browser version - Better JavaScript performance
• Enable hardware acceleration - Faster rendering for large files
• Gzip compression - Significantly reduces file size (use .gz files)
• File size limits - Browser dependent, typically 100MB+ works fine
• Clear cache - If experiencing loading issues
• Split large traces - If file is too large to process

💡 Tip: For sensitive data, use incognito/private browsing mode.

🐛 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 .ndjson.gz files instead of .ndjson
• Ensure parsing completed successfully
• Check browser console for JavaScript errors
• Some lines may not be mapped due to the nature of the IRs.

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

📚 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. Use IR Code View 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

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

• Usage Guide - Generating traces
• Installation Guide - Setup instructions
• Troubleshooting - Common issues
• FAQ - Frequently asked questions