Add Xenon gCPU % to SSA Inspector

Summary:
Add exclusive (leaf) CPU % from the xenon Scuba dataset to the `top` and
`inspect` commands, so users can see whether a hot translation is actually
worth optimizing.

- New file `xenon_fetcher.py`: queries xenon via Bamboo for the top 500
  functions by sample count, computes each function's % of total CPU.
- `top` command now shows a `gCPU=X.XX%` column (or `-` if the function
  isn't in xenon's top 500).
- `inspect` command shows a `Xenon gCPU: X.XX% of total CPU` header line.
- `--xenon-hours N` flag on both commands (default 4, set to 0 to skip).

Reviewed By: ricklavoie

Differential Revision: D94533406

fbshipit-source-id: caef01810fc0eb85532da750f277b0c3d0622e3d

Author: Nikhil Thomas

hphp/tools/ssa-inspector/README.md

@@ -17,26 +17,31 @@ decisions, machine code ranges with disassembly, and profile execution counts.
 # 1. List available runs (find recent data)
 buck run fbcode//hphp/tools/ssa-inspector:main -- list-runs --days 7
 
-# 2. Find the hottest translations in a run
+# 2. Find the hottest translations in a run (includes Xenon gCPU %)
 buck run fbcode//hphp/tools/ssa-inspector:main -- \
-  top --date 2026-02-24 --run-uuid "2026-02-24.prod.web.cln.0-1" --top-n 10
+  top --date 2026-02-25 --run-uuid "2026-02-25.prod.web.cln.0-1" --top-n 10
 
-# 3. Inspect a specific translation in detail
+# 2b. Skip Xenon lookup (faster, no Scuba query)
 buck run fbcode//hphp/tools/ssa-inspector:main -- \
-  inspect --trans-id 90516 \
-  --date 2026-02-24 --run-uuid "2026-02-24.prod.web.cln.0-1" \
+  top --date 2026-02-25 --run-uuid "2026-02-25.prod.web.cln.0-1" --top-n 10 \
+  --xenon-hours 0
+
+# 3. Inspect a specific translation in detail (shows gCPU % in header)
+buck run fbcode//hphp/tools/ssa-inspector:main -- \
+  inspect --trans-id 58753 \
+  --date 2026-02-25 --run-uuid "2026-02-25.prod.web.cln.0-1" \
   --format detail
 
 # 4. Search by function name
 buck run fbcode//hphp/tools/ssa-inspector:main -- \
   inspect --function "contains_key" \
-  --date 2026-02-24 --run-uuid "2026-02-24.prod.web.cln.0-1" \
+  --date 2026-02-25 --run-uuid "2026-02-25.prod.web.cln.0-1" \
   --format summary
 
 # 5. Include machine code disassembly
 buck run fbcode//hphp/tools/ssa-inspector:main -- \
-  inspect --trans-id 90544 \
-  --date 2026-02-24 --run-uuid "2026-02-24.prod.web.cln.0-1" \
+  inspect --trans-id 58753 \
+  --date 2026-02-25 --run-uuid "2026-02-25.prod.web.cln.0-1" \
   --format detail --disasm
 
 # 6. Load from a local trace file (no Hive needed)
@@ -55,6 +60,19 @@ Run `top` to identify the hottest translations by execution count (profCount).
 Focus on `TransOptimize` translations — these are the fully optimized JIT output
 and represent the code that actually runs in production.
 
+By default, the `top` and `inspect` commands also query the **Xenon** Scuba
+dataset (`xenon`) to show each function's **exclusive gCPU %** — what fraction
+of total CPU the function itself consumes (leaf cost, not including callees).
+This answers "is optimizing this function worth it?" since a high profCount
+doesn't necessarily mean high CPU cost.
+
+- `gCPU=0.18%` means the function is 0.18% of total fleet CPU (last 4 hours).
+- `gCPU=    -` means the function isn't in xenon's top 500 — it likely consumes
+  negligible CPU at the leaf level (common for builtins like `ord`, `strlen`
+  whose actual cost is attributed to native code).
+- Use `--xenon-hours N` to change the lookback window (default: 4 hours).
+- Use `--xenon-hours 0` to skip the Xenon query entirely.
+
 ### Step 2: Inspect in Summary Mode
 
 Use `--format summary` to quickly scan a translation's structure. The summary
@@ -164,4 +182,5 @@ Key opcodes and their meanings:
 | `data_fetcher.py` | Presto/Hive queries + local file loading |
 | `ir_parser.py` | JSON blob → dataclass parsing |
 | `formatter.py` | Summary and detail output formatting |
+| `xenon_fetcher.py` | Xenon Scuba queries for gCPU % (exclusive/leaf cost) |
 | `main.py` | CLI entry point (argparse) |

hphp/tools/ssa-inspector/main.py

@@ -12,11 +12,13 @@
 from __future__ import annotations
 
 import argparse
+import json
 import sys
 
 from hphp.tools.ssa_inspector import data_fetcher
 from hphp.tools.ssa_inspector.formatter import format_translation
 from hphp.tools.ssa_inspector.ir_parser import parse_json_blob
+from hphp.tools.ssa_inspector.xenon_fetcher import fetch_gcpu_for_functions
 
 
 def cmd_list_runs(args: argparse.Namespace) -> None:
@@ -42,14 +44,26 @@ def cmd_top(args: argparse.Namespace) -> None:
         print("No translations found.")
         return
 
+    # Fetch xenon gCPU data if requested
+    gcpu_map: dict[str, float] = {}
+    if args.xenon_hours > 0:
+        func_names = list({r.get("func_name", "") for r in rows if r.get("func_name")})
+        gcpu_map = fetch_gcpu_for_functions(func_names, args.xenon_hours)
+
     print(f"Top {len(rows)} translations by profCount:\n")
     for i, r in enumerate(rows, 1):
         pc = r.get("prof_count", 0)
+        func_name = r.get("func_name", "?")
+        gcpu_str = ""
+        if args.xenon_hours > 0:
+            gcpu_pct = gcpu_map.get(func_name)
+            gcpu_str = f"  gCPU={gcpu_pct:>5.2f}%" if gcpu_pct else "  gCPU=    -"
         print(
             f"  {i:3d}. trans_id={r['trans_id']:<8}"
             f"  profCount={pc:>12,}"
+            f"{gcpu_str}"
             f"  kind={r.get('kind', '?'):<18}"
-            f"  {r.get('func_name', '?')}"
+            f"  {func_name}"
         )
 
     if args.format != "list":
@@ -65,6 +79,20 @@ def cmd_top(args: argparse.Namespace) -> None:
             print()
 
 
+def _extract_func_names(rows: list[dict]) -> list[str]:
+    """Extract function names from translation data rows."""
+    func_names: list[str] = []
+    for r in rows:
+        try:
+            data = json.loads(r["data"])
+            name = data.get("translation", {}).get("funcName", "")
+            if name:
+                func_names.append(name)
+        except (json.JSONDecodeError, KeyError):
+            pass
+    return func_names
+
+
 def cmd_inspect(args: argparse.Namespace) -> None:
     if args.local_file:
         rows = data_fetcher.load_from_local_file(
@@ -101,7 +129,28 @@ def cmd_inspect(args: argparse.Namespace) -> None:
         print("No translations found.")
         return
 
-    print(f"Found {len(rows)} translation(s).\n")
+    # Extract function names for xenon lookup
+    func_names = _extract_func_names(rows)
+
+    # Fetch xenon gCPU data if requested
+    gcpu_map: dict[str, float] = {}
+    if args.xenon_hours > 0 and func_names:
+        gcpu_map = fetch_gcpu_for_functions(list(set(func_names)), args.xenon_hours)
+
+    print(f"Found {len(rows)} translation(s).")
+
+    if args.xenon_hours > 0 and func_names:
+        # Show gCPU for the primary function
+        gcpu_pct = gcpu_map.get(func_names[0])
+        if gcpu_pct is not None:
+            print(
+                f"Xenon gCPU: {gcpu_pct:.2f}% of total CPU "
+                f"(last {args.xenon_hours}h, exclusive)"
+            )
+        else:
+            print(f"Xenon gCPU: not in top 500 functions (last {args.xenon_hours}h)")
+
+    print()
     for r in rows:
         translation = parse_json_blob(r["data"])
         print(format_translation(translation, fmt=args.format, show_disasm=args.disasm))
@@ -142,6 +191,12 @@ def main() -> None:
         action="store_true",
         help="Include machine code disassembly",
     )
+    p_top.add_argument(
+        "--xenon-hours",
+        type=int,
+        default=4,
+        help="Xenon lookback window in hours for gCPU %% (0 to skip, default: 4)",
+    )
     p_top.set_defaults(func=cmd_top)
 
     # inspect
@@ -169,6 +224,12 @@ def main() -> None:
         action="store_true",
         help="Include machine code disassembly",
     )
+    p_inspect.add_argument(
+        "--xenon-hours",
+        type=int,
+        default=4,
+        help="Xenon lookback window in hours for gCPU %% (0 to skip, default: 4)",
+    )
     p_inspect.set_defaults(func=cmd_inspect)
 
     args = parser.parse_args()

hphp/tools/ssa-inspector/xenon_fetcher.py

@@ -0,0 +1,67 @@
+# (c) Meta Platforms, Inc. and affiliates. Confidential and proprietary.
+
+"""
+Fetch Xenon gCPU data from the xenon Scuba dataset.
+
+Provides exclusive (leaf) CPU % for PHP functions, matching the fn_name
+column format used by tcprint (ClassName::methodName).
+"""
+
+from __future__ import annotations
+
+from analytics.bamboo import Bamboo as bb
+
+
+def _escape_scuba_sql(s: str) -> str:
+    """Escape a string for use in a Scuba SQL string literal.
+
+    Backslashes in PHP namespaces (e.g. FlibSL\\C\\contains_key) need
+    to be doubled in Scuba SQL.
+    """
+    return s.replace("\\", "\\\\").replace("'", "\\'")
+
+
+def fetch_gcpu_for_functions(
+    function_names: list[str],
+    lookback_hours: int = 4,
+) -> dict[str, float]:
+    """Return {func_name: gcpu_pct} for each function.
+
+    Queries xenon for exclusive CPU % (leaf cost) using the fn_name column.
+    Returns percentages as floats (e.g. 0.12 means 0.12% of total CPU).
+    """
+    if not function_names:
+        return {}
+
+    query = (
+        f"SELECT `fn_name`, COUNT(1) AS `sample_count` "
+        f"FROM `xenon` "
+        f"WHERE `time` >= NOW() - {lookback_hours} * 3600 "
+        f"AND `is_io` = '0' "
+        f"GROUP BY `fn_name` "
+        f"ORDER BY `sample_count` DESC "
+        f"LIMIT 500"
+    )
+
+    df = bb.query_scuba_nullable(sql=query)
+
+    if df.empty:
+        return {}
+
+    # Build a map of fn_name -> sample_count from the results
+    total_samples = int(df["sample_count"].sum())
+    if total_samples == 0:
+        return {}
+
+    name_to_count: dict[str, int] = dict(
+        zip(df["fn_name"].astype(str), df["sample_count"].astype(int))
+    )
+
+    # Compute gCPU % for requested functions
+    result: dict[str, float] = {}
+    for func in function_names:
+        count = name_to_count.get(func, 0)
+        if count > 0:
+            result[func] = round(count / total_samples * 100, 4)
+
+    return result