From f6ed8760adea10fd451b6b247119135d4cdaa91d Mon Sep 17 00:00:00 2001 From: Jiten Thakkar Date: Thu, 2 Jul 2026 13:55:02 -0700 Subject: [PATCH] Add LLO analysis and query tools to xprof_cli. This change adds the ability to parse LLO (Low Level Operator) events from XSpace TPU device planes and load them into a SQLite database for querying. This mirrors the analysis features of percale_cli. Specifically, this CL: - Implements llo_parser.py to extract LLO events (SALU, VALU, EUP, XLU, etc.) and stats, and populate a SQLite schema. - Implements llo_tools.py with llo_load and llo_query commands. - Registers the new commands in xprof_cli.py. - Adds comprehensive unit, integration, stress, and adversarial tests. - Adds README.md documenting the commands. PiperOrigin-RevId: 941814052 --- plugin/xprof/cli/README.md | 66 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 66 insertions(+) create mode 100644 plugin/xprof/cli/README.md diff --git a/plugin/xprof/cli/README.md b/plugin/xprof/cli/README.md new file mode 100644 index 000000000..c275b3da4 --- /dev/null +++ b/plugin/xprof/cli/README.md @@ -0,0 +1,66 @@ + +# XProf CLI + +`xprof_cli` is a command-line interface tool for interacting with Google's XProf profiling data. It provides various commands to extract, analyze, and query different aspects of TPU and GPU profiles. + +## Usage + +```bash +bazel run //third_party/xprof/plugin/xprof/cli:xprof_cli -- [args...] +``` + +## Available Commands and Parameters + +The CLI exposes numerous tools for analysis. Most tools require at least a `--session_id`. + +* **`llo_load`**: Load LLO traces from a session into a SQLite DB. + * `--session_id=`: The XProf session ID. + * `--db_path=`: Path to the SQLite database file. +* **`llo_query`**: Query a generated LLO SQLite DB. + * `--db_path=`: Path to the SQLite database file. + * `--query=`: SQL query string or pre-baked query name. +* **`get_overview`**: Get high-level overview of a session. + * `--session_id=` + * `--include_command=` (Optional) +* **`get_memory_profile`**: Analyze memory allocations. + * `--session_id=` +* **`get_top_hlo_ops`**: Fetch the most expensive HLO operations. + * `--session_id=` + * `--limit=` (Optional, default 10) +* **`get_kpi_metrics`**: Get Key Performance Indicators. + * `--session_id=` +* **`detect_unfused_reshapes`**: Find reshapes that aren't fused. + * `--session_id=` +* **`diff_sessions`**: Compare two profiling sessions. + * `--session_id_1=` + * `--session_id_2=` +* **`find_session`**: Locate an XProf session. + * `--session_id=` +* **`get_events_db_session_root`**: Locate the events DB session root. + * `--session_id=` +* **`get_graph_viewer`**: Fetch graph viewer data. + * `--session_id=` + * `--graph_type=` (Optional) + * `--output_type=` (Optional) + * `--show_metadata=` (Optional) + * `--graph_width=` (Optional) + * `--merge_fusion=` (Optional) +* **`get_hlo_neighborhood`**: Get the neighborhood of an HLO instruction. + * `--session_id=` + * `--module_name=` + * `--instruction_name=` +* **`get_hlo_text`**: Get textual representation of an HLO module. + * `--session_id=` + * `--module_name=` +* **`get_peak_allocations`**: Identify peak memory allocations. + * `--session_id=` +* **`get_smart_suggestions`**: Receive automated performance suggestions. + * `--session_id=` +* **`get_utilization_viewer`**: Fetch utilization data. + * `--session_id=` +* **`detect_layout_mismatch_copies`**: Find copies caused by layout mismatches. + * `--session_id=` + +## LLO (Low Level Operator) Analysis + +For detailed instructions on extracting, loading, and querying LLO events, see the [LLO Analysis Documentation](internal/google/README.md).