Skip to content

03. Web Interface Guide

Jump to bottom
github-actions[bot] edited this page Sep 3, 2026 · 12 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://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

Bundled Examples

Two example traces ship with the site. Regenerate them with make regen-examples-install WORKLOAD=triton and make regen-examples-install WORKLOAD=inductor, respectively:

Example Contents
Hand-written Triton An autotuned matmul and a fused elementwise kernel. Has launch data, so launch diffs, per-launch roofline and the autotune session views are all populated.
Inductor Kernels torch.compile generated, across two compile frames. Their Python source is inductor's generated output_code.py, not a kernel anyone wrote by hand.

The inductor example has no launch-level data. tritonparse's launch metadata is attached by its JIT hook, and inductor launches through its own CachingAutotuner launcher, which does not carry that payload — so launch diffs and roofline are empty for it.

🎯 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

💡 Tip: The kernel selector 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

💡 Tip: Tensor arguments 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: From Overview or IR Code View tabs, click "Compare in File Diff" button to switch to File Diff with your current kernel pre-selected

💡 Preview Mode allows seamless navigation between tabs while preserving your kernel selection.

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

💡 Tip: Copy buttons are 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

💡 Tip: 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

Performance Analysis

Goal: Identify optimization opportunities

Steps:

  1. Check kernel metadata for register usage, shared memory
  2. Examine TTGIR for memory access patterns
  3. Review PTX/AMDGCN for vectorization and instruction scheduling
  4. Compare with File Diff before/after optimization attempts
  5. Generate reproducer for isolated benchmarking (see Reproducer Guide)

Debugging Workflow

Goal: Track down kernel issues

Steps:

  1. Start from Overview - check compilation metadata and call stack
  2. Review launch analysis - identify varying parameters
  3. Examine IRs progressively: TTIR → TTGIR → LLIR → PTX
  4. Use source mapping to trace problematic code sections
  5. Generate reproducer for isolated debugging
  6. Compare with File Diff against working version if available

Cross-Version Comparison

Goal: Validate changes across compiler versions or code modifications

Steps:

  1. Generate traces from both versions with same input
  2. Open File Diff View with both traces
  3. Compare each IR stage systematically
  4. Focus on PTX/AMDGCN for final code generation differences
  5. Document findings using URL sharing

📱 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. Master Reproducer Generation for debugging and benchmarking
  5. Join GitHub Discussions

📚 Related Documentation

TritonParse Wiki

Clone this wiki locally