{"id":8716,"library":"tlparse","title":"tlparse","description":"tlparse is a command-line utility for parsing structured `TORCH_LOG` logs generated by PyTorch's `torch.compile`. It analyzes these logs and outputs rich HTML reports, aiding in understanding the compilation process, identifying graph breaks, recompilations, and debugging dynamic shape issues. The current version is 0.4.3, and it is actively maintained within the PyTorch ecosystem.","status":"active","version":"0.4.3","language":"en","source_language":"en","source_url":"https://github.com/meta-pytorch/tlparse","tags":["pytorch","debugging","profiling","logs","torch.compile","performance"],"install":[{"cmd":"pip install tlparse","lang":"bash","label":"Install tlparse"}],"dependencies":[],"imports":[],"quickstart":{"code":"import os\nimport torch\n\n@torch.compile\ndef my_model(x):\n    return x + x\n\ndef run_model_with_trace():\n    log_dir = os.path.join(os.getcwd(), \"my_traced_log_dir\")\n    os.makedirs(log_dir, exist_ok=True)\n    \n    # Set TORCH_TRACE environment variable to collect logs\n    os.environ['TORCH_TRACE'] = log_dir\n    \n    try:\n        x = torch.randn(10, 10)\n        _ = my_model(x)\n        print(f\"Logs generated in: {log_dir}\")\n        print(f\"Now run: tlparse {log_dir} -o tl_out/ --latest\")\n    finally:\n        # Clean up the environment variable after use\n        del os.environ['TORCH_TRACE']\n\nif __name__ == \"__main__\":\n    run_model_with_trace()","lang":"python","description":"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."},"warnings":[{"fix":"Update custom Rust parsers to match the new `parse_path` signature.","message":"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.","severity":"breaking","affected_versions":">=0.4.0"},{"fix":"Review log contents before sharing, especially in public forums or bug reports. Consider anonymizing sensitive code sections if necessary.","message":"`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.","severity":"gotcha","affected_versions":"all"},{"fix":"Always share the complete output directory (e.g., a zip of `tl_out/`) or the original `TORCH_TRACE` log directory.","message":"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.","severity":"gotcha","affected_versions":"all"},{"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.","message":"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.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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).","cause":"The `tlparse` executable is not in your system's PATH, or the package was not installed correctly.","error":"command not found: tlparse"},{"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.","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.","error":"tlparse /tmp/my_traced_log_dir --latest produces 'No logs found in /tmp/my_traced_log_dir.'"},{"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.","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).","error":"The tlparse output HTML report does not automatically open in my web browser."}]}