06. FAQ

This page addresses common questions and issues encountered when using TritonParse.

� Quick Reference

Most frequently asked questions:

1. What is TritonParse?
2. How do I install it?
3. How do I generate traces?
4. Why are my traces empty?
5. Can't see source mappings?
6. How do I compare kernels?
7. How do I generate a reproducer?

---

�🚀 Getting Started

Q: What is TritonParse?

A: TritonParse is a comprehensive visualization and analysis tool for Triton IR files. It helps developers analyze, debug, and understand Triton kernel compilation processes by:

• Capturing structured compilation and launch logs
• Providing interactive visualization of IR stages and launch events
• Mapping transformations between compilation stages
• Offering side-by-side IR code viewing

Q: Do I need to install anything to use TritonParse?

A: It depends on your use case:

• For analysis only: No installation needed! Just visit https://meta-pytorch.org/tritonparse/
• For generating traces: You need to install the Python package (pip install -e .)
• For development: You need the full development setup

Q: What are the system requirements?

A:

• Python >= 3.10
• Triton >= 3.4.0 (PyPI installation is now recommended)
• GPU Support (for GPU tracing):
  • NVIDIA GPUs: CUDA 11.8+ or 12.x
  • AMD GPUs: ROCm 5.0+ (MI100, MI200, MI300 series)
• Modern browser (Chrome 90+, Firefox 88+, Safari 14+, Edge 90+)

🔧 Installation and Setup

Q: How do I install Triton?

A: Install from PyPI (recommended):

pip install triton

💡 For building from source or development setup, see Installation Guide.

Q: I'm getting "No module named 'triton'" errors. What's wrong?

A: This usually means:

1. Triton isn't installed - Install from source (see above)
2. Wrong Python environment - Make sure you're in the right virtual environment
3. Installation failed - Check for compilation errors during Triton installation

Q: Do I need a GPU to use TritonParse?

A: Yes, a GPU is required because Triton itself depends on GPU:

• For generating traces: GPU is required (either NVIDIA with CUDA or AMD with ROCm)
• For web interface only: No GPU needed (just to view existing trace files from others)

Note: Triton kernels can only run on GPU, so you need GPU hardware to generate your own traces.

📊 Generating & Analyzing Traces

Q: How do I generate trace files?

A: Initialize logging before running kernels, then parse:

import tritonparse.structured_logging
import tritonparse.utils

tritonparse.structured_logging.init("./logs/", enable_trace_launch=True)
# Your kernel code here
tritonparse.utils.unified_parse(source="./logs/", out="./parsed_output")

💡 See Usage Guide for complete examples.

Q: My trace files are empty. What's wrong?

A: Common causes:

1. Logging not initialized - Make sure you call tritonparse.structured_logging.init() before kernel execution
2. No kernel execution - Ensure your code actually executes Triton kernels
3. Cache issues - Set TORCHINDUCTOR_FX_GRAPH_CACHE=0 environment variable
4. Permissions - Check that the log directory is writable

Q: What's the difference between .ndjson and .gz files?

A:

• .ndjson: Raw trace logs, no source mapping, good for debugging
• .gz: Compressed parsed traces with full source mapping, recommended for analysis

Always use .gz files for full functionality in the web interface.

🌐 Web Interface & Features

Q: Can I use TritonParse without uploading my traces to the internet?

A: Yes! The web interface runs entirely in your browser:

• No data is sent to servers
• Files are processed locally
• Use the online interface safely at https://meta-pytorch.org/tritonparse/

Q: Why can't I see source mappings in the web interface?

A:

1. Using .ndjson files - Switch to .gz files from parsed_output directory
2. Parsing failed - Check that unified_parse() completed successfully
3. Browser issues - Try refreshing the page or using a different browser

Q: The web interface is slow. How can I improve performance?

A: Try these solutions:

• Use smaller trace files (filter specific kernels)
• Enable browser hardware acceleration
• Use Chrome (recommended browser)
• Close other tabs to free memory

Q: How do I share my analysis with others?

A: Options:

• Host trace files and share URL: ?json_url=YOUR_FILE_URL
• Take screenshots of findings
• Export browser bookmarks

💡 The web interface runs locally - no data is uploaded to servers.

Q: How do I understand the different IR stages?

A: Here's the compilation pipeline:

Stage	Description	When to Use
TTIR	Triton IR - High-level language constructs	Understanding kernel logic
TTGIR	Triton GPU IR - GPU-specific operations	GPU-specific optimizations
LLIR	LLVM IR - Low-level operations	Compiler optimizations
PTX	NVIDIA assembly	Final code generation
AMDGCN	AMD assembly	AMD GPU final code

Q: What should I look for when analyzing performance?

A: Key areas:

• Memory access patterns and coalescing
• Register usage in metadata
• Vectorization in transformations
• Branch divergence in control flow

💡 See Web Interface Guide for detailed workflows.

Q: How do I debug compilation failures?

A: Follow this order:

1. Check call stack for error location
2. Start with TTIR for syntax issues
3. Check LLIR for type problems
4. Verify PTX for hardware compatibility
5. Enable debug: TRITONPARSE_DEBUG=1

Q: How do I compare kernels from different traces?

A: Use the File Diff tab or URL:

?view=file_diff&json_url=trace1.gz&json_b_url=trace2.gz

Steps:

1. Load two trace files (left/right)
2. Select kernels to compare
3. Choose IR type and mode (single/all)

💡 See File Diff Guide for all features and URL parameters.

Q: What diff options are available?

A: Customize the diff display:

• Ignore whitespace (default: true)
• Word vs line-level diff (default: word)
• Context lines (default: 3)
• Word wrap and show-only-changes

Details: Diff Options

🔧 Tools & CLI

� File Diff View

Q: How do I use the File Diff functionality?

A: The File Diff View allows comparing kernels across two different trace files:

1. Access: Click the "File Diff" tab in the main interface or use ?view=file_diff in the URL
2. Load Left Source: Use the currently loaded trace or load via URL/file
3. Load Right Source: Enter URL in "Right Source" field or upload a file
4. Select Kernels: Choose kernels from each side's dropdown
5. Choose IR and Mode: Select which IR to compare and single/all mode
6. Adjust Options: Configure diff display (whitespace, word-level, context, etc.)

Q: What are the URL parameters for File Diff?

A: Complete URL parameter reference:

?view=file_diff
&json_url=LEFT_TRACE_URL          # Left trace file
&json_b_url=RIGHT_TRACE_URL        # Right trace file
&kernel_hash_a=LEFT_KERNEL_HASH    # Pre-select left kernel
&kernel_hash_b=RIGHT_KERNEL_HASH   # Pre-select right kernel
&mode=single                        # or 'all'
&ir=ttgir                          # IR type
&ignore_ws=true                    # Ignore whitespace
&word_level=true                   # Word-level diff
&context=3                         # Context lines
&wrap=on                           # Word wrap
&only_changed=false                # Show only changes

Q: How do I compare kernels from different trace files?

A: Two approaches:

Using URLs:

https://meta-pytorch.org/tritonparse/?view=file_diff&json_url=trace1.gz&json_b_url=trace2.gz

Using Local Files:

1. Go to File Diff tab
2. Upload first file on left side
3. Upload second file on right side
4. Select kernels to compare

Q: What diff options are available?

A: Customizable diff options:

• Ignore Whitespace: Ignore spaces/indentation (default: true)
• Word-level Diff: Highlight at word vs line level (default: true)
• Context Lines: Unchanged lines around changes (default: 3)
• Word Wrap: Wrap long lines or scroll (default: on)
• Only Changes: Hide unchanged sections (default: false)

Q: Can I compare different kernels (not just same kernel across versions)?

A: Yes! You can compare any two kernels:

1. Select different kernels from left and right dropdowns
2. Useful for comparing alternative implementations
3. Side-by-side view helps spot algorithmic differences

🔧 Reproducer

Q: How do I generate a reproducer script?

A: Use the CLI or Python API:

tritonparse reproduce trace.ndjson --line 1 --out-dir repro_output

💡 See Reproducer Guide for templates and advanced options.

Q: Does the reproducer use real tensor data?

A: Depends on tracing configuration:

• Real data: If save_tensor_blobs=True was enabled during tracing
• Synthetic: Generated from saved statistics (mean, std, min, max)
• Random: Fallback if no statistics available

Details: Tensor Strategies

Q: What CLI commands are available?

A: TritonParse now uses subcommands:

# New style (recommended)
tritonparse parse ./logs/ --out ./parsed_output
tritonparse reproduce trace.ndjson --line 1

# Also works with python -m
python -m tritonparse parse ./logs/

💡 See CLI Reference for all parameters.

Q: What environment variables are supported?

A: Key environment variables:

Variable	Description	Example
TRITON_TRACE_FOLDER	Trace output directory	"./logs/"
TRITON_TRACE_LAUNCH	Enable launch tracing	"1"
TRITONPARSE_DEBUG	Enable debug logging	"1"
TRITONPARSE_KERNEL_ALLOWLIST	Filter kernels	"kernel1*"
TORCHINDUCTOR_FX_GRAPH_CACHE	Disable cache	"0"

Usage: Environment Variables Guide

🐛 Troubleshooting

Q: How do I use the tritonparse command after installation?

A: After installing TritonParse, you can use it as a command:

# Install
pip install tritonparse

# Use as command
tritonparse parse ./logs/ --out ./parsed_output
tritonparse reproduce trace.ndjson --line 1

# Or with python -m
python -m tritonparse parse ./logs/ --out ./parsed_output
python -m tritonparse reproduce trace.ndjson --line 1

Q: How do I use init_with_env()?

A: Initialize TritonParse from environment variables:

import tritonparse.structured_logging
import os

# Set environment variables
os.environ["TRITON_TRACE_FOLDER"] = "./logs/"
os.environ["TRITON_TRACE_LAUNCH"] = "1"

# Initialize from environment
tritonparse.structured_logging.init_with_env()

Or from shell:

export TRITON_TRACE_FOLDER="./logs/"
export TRITON_TRACE_LAUNCH="1"
python my_script.py  # Uses init_with_env() inside

Q: What are the new environment variables?

A: TritonParse supports these environment variables:

Variable	Description	Example
TRITON_TRACE_FOLDER	Trace output directory	"./logs/"
TRITON_TRACE_LAUNCH	Enable launch tracing	"1"
TRITONPARSE_DEBUG	Enable debug logging	"1"
TRITON_TRACE_GZIP	Enable gzip compression	"1"
TRITONPARSE_KERNEL_ALLOWLIST	Filter kernels	"kernel1*,kernel2*"
TORCHINDUCTOR_FX_GRAPH_CACHE	Disable cache (for testing)	"0"

�🐛 Common Issues

Q: My trace files are empty. What's wrong?

A: Common causes:

• Logging not initialized before kernel execution
• No Triton kernels actually ran
• Cache issues: Set TORCHINDUCTOR_FX_GRAPH_CACHE=0
• Check log directory is writable

Q: Why can't I see source mappings in the web interface?

A: Solutions:

• Use .gz files from parsed_output/ (not raw .ndjson)
• Ensure unified_parse() completed successfully
• Try refreshing browser or using Chrome

Q: My kernels aren't showing up in the trace.

A: Check:

• Kernel code actually executed
• Set TORCHINDUCTOR_FX_GRAPH_CACHE=0
• Logging initialized before kernel runs
• Each process has its own log directory (multi-process)

Q: How do I trace only specific kernels?

A: Use kernel allowlist:

export TRITONPARSE_KERNEL_ALLOWLIST="my_kernel*,important_*"

💡 For more issues, see Troubleshooting

Q: Can I use TritonParse with multiple GPUs?

A: Yes! Parse with rank options:

# All ranks
tritonparse parse ./logs/ --out ./parsed_output --all-ranks

# Specific rank
tritonparse parse ./logs/ --out ./parsed_output --rank 1

🤝 Contributing & Resources

Q: How can I contribute to TritonParse?

A:

• Check Contributing Guide
• Browse GitHub Issues
• Join GitHub Discussions

Q: Where can I get help?

A:

• GitHub Discussions - Community Q&A
• GitHub Issues - Bug reports
• This Wiki - Comprehensive documentation

Q: How do I report bugs?

A: Include in your report:

• System info (Python version, OS, GPU)
• TritonParse version
• Minimal reproduction code
• Complete error logs

Template: GitHub Issue Template

Q: Where can I learn more about Triton?

A:

• Triton Documentation
• Triton Tutorials
• Triton Puzzles

Q: Are there example use cases?

A: Yes! Check:

• Basic Examples
• Advanced Examples
• tests/ directory in repository
• GitHub Discussions

---

🔗 Quick Links

• 🏠 Home - Wiki home page
• 📚 Installation - Setup instructions
• 📖 Usage Guide - Complete usage tutorial
• 🌐 Web Interface Guide - Interface walkthrough
• 🔧 Developer Guide - Contributing and development
• ❓ GitHub Discussions - Community Q&A

---

Can't find your question?

• Search the GitHub Issues for similar problems
• Ask in GitHub Discussions
• Check the other wiki pages for more detailed information