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

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?

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

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

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+)

A: Install from PyPI (recommended):

pip install triton

💡 For the latest Triton installation guidance, visit triton-lang.org.

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

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.

A: Initialize logging before running kernels, then parse:

import tritonparse.structured_logging
import tritonparse.parse.utils

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

💡 See Usage Guide for complete examples.

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

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.

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/

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

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

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.

A: Here's the compilation pipeline:

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.

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

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.

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

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.)

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

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

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)

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

A: Use the CLI or Python API:

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

💡 See Reproducer Guide for templates and advanced options.

A: Depends on tracing configuration:

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

Details: Tensor Strategies

A: TritonParse now uses subcommands:

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

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

💡 See CLI Reference for all parameters.

A: Key environment variables:

Usage: Environment Variables Guide

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

# Install
pip install tritonparse

# Use as command (OSS)
tritonparseoss parse ./logs/ --out ./parsed_output
tritonparseoss 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

A: Initialize TritonParse from environment variables:

import tritonparse.structured_logging
import os

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

# Initialize from environment
tritonparse.structured_logging.init_with_env()

Or from shell:

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

A: TritonParse supports these environment variables:

💡 See Environment Variables Reference for complete documentation of all variables.

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

A: Solutions:

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

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)

A: Use kernel allowlist:

export TRITONPARSE_KERNEL_ALLOWLIST="my_kernel*,important_*"

💡 For more issues, see Troubleshooting

A: Yes! Parse with rank options:

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

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

A: Yes. The schema is _rank_*_pid_{PID}_host_{HOST}_, where * is either an integer rank or the literal none (for pre-dist.init or single-GPU runs). The PID + host segments isolate each process to prevent multi-process write corruption and disambiguate PIDs across machines. The always-present _rank_*_ token lets MAST downloads use a single regex LOG_PREFIX.*_rank_(N|none)_ to fetch rank N + the matching pre-init no-rank file in one call — no prefix-match overdownload needed. Older files without one or more of these suffixes still parse locally, but legacy files lacking the _rank_*_ token are not pulled by MAST --rank N / --rank none (use --all-ranks). See Trace File Naming.

A: This is the pre-init kernel attribution behavior. Kernels compiled before dist.init_process_group() previously appeared only under rank_none. They now show up under their owning rank because TritonParse can correlate the no-rank trace file with the ranked one via the shared (host, pid) identifier. To restore the old behavior (separate rank_none bucket), pass --no-pre-init-attribution.

A:

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

A:

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

A: Include in your report:

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

Template: GitHub Issue Template

A:

• Triton Documentation
• Triton Tutorials
• Triton Puzzles

A: Yes! Check:

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

• 🏠 Home - Wiki home page
• 📚 Installation - Setup instructions
• 📖 Usage Guide - Complete usage tutorial
• 🌐 Web Interface Guide - Interface walkthrough
• 🔧 Developer Guide - Contributing and development
• 🔄 Environment Variables - Configuration reference
• 📘 Python API Reference - API documentation
• 🔬 Reproducer Guide - Standalone script generation
• ❓ 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