tlparse

Common errors

• command not found: tlparse

  cause The `tlparse` executable is not in your system's PATH, or the package was not installed correctly.
  fix Ensure `pip install tlparse` completed successfully and verify that your shell's PATH environment variable includes the directory where pip installs scripts (e.g., `~/.local/bin` on Linux/macOS or `C:\PythonXX\Scripts` on Windows).

• tlparse /tmp/my_traced_log_dir --latest produces 'No logs found in /tmp/my_traced_log_dir.'

  cause The `TORCH_TRACE` environment variable was not set correctly before running the PyTorch program, the program did not execute `torch.compile` pathways that generate logs, or `tlparse` is pointed to an empty or incorrect directory.
  fix Rerun your PyTorch script with `TORCH_TRACE="/tmp/my_traced_log_dir" python your_script.py`. Double-check that the specified directory exists and contains log files before running `tlparse` on it.

• The tlparse output HTML report does not automatically open in my web browser.

  cause The `tlparse` command-line tool attempts to open the browser, but this functionality might fail in certain execution environments (e.g., remote SSH sessions, CI/CD pipelines, or systems without a default browser configured).
  fix Manually navigate to the output directory (default is `tl_out/` relative to where `tlparse` was run) and open the `index.html` file in your preferred web browser.

Warnings

• breaking The `parse_path` function signature changed in version 0.4.0 (from `ParseConfig` to `&ParseConfig`). This primarily affects developers extending `tlparse` with custom parsers in Rust, not typical Python users of the CLI.
  Fix: Update custom Rust parsers to match the new `parse_path` signature.
• gotcha `TORCH_TRACE` logs contain your model's source code. Exercise caution when sharing these logs as they can expose intellectual property, although they do not contain model weights.
  Fix: Review log contents before sharing, especially in public forums or bug reports. Consider anonymizing sensitive code sections if necessary.
• gotcha When submitting `tlparse` reports for bug fixes, simply attaching `index.html` is insufficient. The `index.html` only provides a catalogue; PyTorch developers typically need the entire `tl_out` directory (or a compressed archive of it) or the raw `TORCH_TRACE` log directory for full context.
  Fix: Always share the complete output directory (e.g., a zip of `tl_out/`) or the original `TORCH_TRACE` log directory.
• gotcha tlparse helps identify performance bottlenecks like 'graph breaks' (light green frames) and 'recompilations' (frames like `[10/0] [10/1] [10/2]`) in `torch.compile` output. These indicate lost optimization opportunities and should be investigated.
  Fix: Simplify code, reduce data-dependent operations, or adopt compiler-friendly patterns in your PyTorch model to minimize graph breaks and recompilations. Consult PyTorch `torch.compile` documentation for best practices.

Install

• pip install tlparse Install tlparse

Quickstart

To use `tlparse`, first run your PyTorch script with the `TORCH_TRACE` environment variable set to a desired log directory. Then, execute the `tlparse` command-line tool on that directory to generate an HTML report. This example demonstrates how to set up log generation and provides the subsequent `tlparse` command.

import os
import torch

@torch.compile
def my_model(x):
    return x + x

def run_model_with_trace():
    log_dir = os.path.join(os.getcwd(), "my_traced_log_dir")
    os.makedirs(log_dir, exist_ok=True)
    
    # Set TORCH_TRACE environment variable to collect logs
    os.environ['TORCH_TRACE'] = log_dir
    
    try:
        x = torch.randn(10, 10)
        _ = my_model(x)
        print(f"Logs generated in: {log_dir}")
        print(f"Now run: tlparse {log_dir} -o tl_out/ --latest")
    finally:
        # Clean up the environment variable after use
        del os.environ['TORCH_TRACE']

if __name__ == "__main__":
    run_model_with_trace()