Skip to content

armgit / uzu

Public Imported from GitHub
0

A high-performance inference engine for AI models

update table

Eugene Bokhan09f6309cc53a
diff --git a/.gitignore b/.gitignore
index 28763c5f9..43da88df2 100644
--- a/.gitignore
+++ b/.gitignore
@@ -26,3 +26,4 @@
/crates/uzu/examples/quick_chat.rs
/external
+tools/gpu_trace/*.json
diff --git a/tools/gpu_trace/pyproject.toml b/tools/gpu_trace/pyproject.toml
index 8907af9b8..f52012223 100644
--- a/tools/gpu_trace/pyproject.toml
+++ b/tools/gpu_trace/pyproject.toml
@@ -3,7 +3,7 @@ name = "gpu-trace"
version = "0.1.0"
description = "Record, analyze, and export Metal GPU traces"
requires-python = ">=3.12"
-dependencies = ["cattrs>=24.1.0"]
+dependencies = ["cattrs>=24.1.0", "rich>=13.0.0"]
[project.scripts]
gpu_trace = "gpu_trace.main:cli"
diff --git a/tools/gpu_trace/src/gpu_trace/formatting.py b/tools/gpu_trace/src/gpu_trace/formatting.py
index ba7f65358..56204edbc 100644
--- a/tools/gpu_trace/src/gpu_trace/formatting.py
+++ b/tools/gpu_trace/src/gpu_trace/formatting.py
@@ -1,7 +1,19 @@
from __future__ import annotations
+import shutil
+
+from rich import box
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+from rich.text import Text
+
from .models import KernelCounterStats, TraceExport
+# Use terminal width or sensible default (minimum 140 for readable tables)
+_term_width = shutil.get_terminal_size((140, 24)).columns
+console = Console(width=max(_term_width, 140))
+
def _fmt_ns(ns: int) -> str:
if ns >= 1_000_000_000:
@@ -14,7 +26,7 @@ def _fmt_ns(ns: int) -> str:
def _fmt_percent(value: float) -> str:
- return f"{value:.2f}%"
+ return f"{value:.1f}%"
def _bar(value: float, width: int = 20) -> str:
@@ -22,6 +34,16 @@ def _bar(value: float, width: int = 20) -> str:
return "█" * filled + "░" * (width - filled)
+def _color_percent(value: float) -> tuple[str, str]:
+ if value >= 80:
+ return f"{value:.1f}%", "green"
+ if value >= 50:
+ return f"{value:.1f}%", "yellow"
+ if value >= 20:
+ return f"{value:.1f}%", "dim"
+ return f"{value:.1f}%", "red"
+
+
def _find_bottleneck(counter_dict: dict[str, float]) -> tuple[str, float] | None:
limiters = [
("ALU Limiter", "ALU"),
@@ -49,179 +71,241 @@ def _find_bottleneck(counter_dict: dict[str, float]) -> tuple[str, float] | None
def _print_kernel_detail(kcs: KernelCounterStats) -> None:
counter_dict = dict(kcs.counters)
- name = kcs.name[:50] if len(kcs.name) <= 50 else kcs.name[:47] + "..."
- header = f" {name} ({kcs.count} calls, {_fmt_ns(kcs.total_ns)} total)"
-
- print("┌" + "─" * 78 + "┐")
- print("│" + header.ljust(78) + "│")
- print("├" + "─" * 78 + "┤")
+ table = Table(
+ title=f"[bold cyan]{kcs.name}[/]",
+ caption=f"{kcs.count}× calls = {_fmt_ns(kcs.total_ns)} total",
+ box=box.ROUNDED,
+ show_header=False,
+ padding=(0, 1),
+ )
+ table.add_column("Category", style="yellow", width=12)
+ table.add_column("Details", min_width=60)
alu_lim = counter_dict.get("ALU Limiter", 0)
alu_util = counter_dict.get("ALU Utilization", 0)
f32 = counter_dict.get("F32 Utilization", 0)
f16 = counter_dict.get("F16 Utilization", 0)
- row = f" ALU: Limiter {alu_lim:>5.1f}% Util {alu_util:>5.1f}% F32 {f32:>5.1f}% F16 {f16:>5.1f}%"
- print("│" + row.ljust(78) + "│")
+ table.add_row(
+ "ALU",
+ f"Util [green]{alu_util:>5.1f}%[/] Limiter {alu_lim:>5.1f}% F32 {f32:>5.1f}% F16 {f16:>5.1f}%",
+ )
- buf_rd_lim = counter_dict.get("Buffer Read Limiter", 0)
buf_ld = counter_dict.get("Buffer Load Utilization", 0)
- buf_wr_lim = counter_dict.get("Buffer Write Limiter", 0)
+ buf_rd_lim = counter_dict.get("Buffer Read Limiter", 0)
buf_st = counter_dict.get("Buffer Store Utilization", 0)
- row = f" Buffer: RdLim {buf_rd_lim:>5.1f}% Load {buf_ld:>5.1f}% WrLim {buf_wr_lim:>5.1f}% Store {buf_st:>5.1f}%"
- print("│" + row.ljust(78) + "│")
+ buf_wr_lim = counter_dict.get("Buffer Write Limiter", 0)
+ table.add_row(
+ "Buffer",
+ f"Load {buf_ld:>5.1f}% (lim {buf_rd_lim:>5.1f}%) Store {buf_st:>5.1f}% (lim {buf_wr_lim:>5.1f}%)",
+ )
gpu_rd = counter_dict.get("GPU Read Bandwidth", 0)
gpu_wr = counter_dict.get("GPU Write Bandwidth", 0)
- row = f" Memory: Read {gpu_rd:>6.1f} GB/s Write {gpu_wr:>6.1f} GB/s"
- print("│" + row.ljust(78) + "│")
+ table.add_row(
+ "Memory",
+ f"Read [cyan]{gpu_rd:>6.1f}[/] GB/s Write [cyan]{gpu_wr:>6.1f}[/] GB/s",
+ )
- llc_lim = counter_dict.get("GPU Last Level Cache Limiter", 0)
llc_util = counter_dict.get("GPU Last Level Cache Utilization", 0)
- tex_lim = counter_dict.get("Texture Sample Limiter", 0)
+ llc_lim = counter_dict.get("GPU Last Level Cache Limiter", 0)
tex_util = counter_dict.get("Texture Sample Utilization", 0)
- row = f" Cache: LLC Lim {llc_lim:>5.1f}% Util {llc_util:>5.1f}% Tex {tex_lim:>5.1f}%/{tex_util:>5.1f}%"
- print("│" + row.ljust(78) + "│")
+ tex_lim = counter_dict.get("Texture Sample Limiter", 0)
+ table.add_row(
+ "Cache",
+ f"LLC {llc_util:>5.1f}% (lim {llc_lim:>5.1f}%) Texture {tex_util:>5.1f}% (lim {tex_lim:>5.1f}%)",
+ )
- tg_ld_lim = counter_dict.get("Threadgroup/Imageblock Load Limiter", 0)
tg_ld = counter_dict.get("Threadgroup/Imageblock Load Utilization", 0)
- tg_st_lim = counter_dict.get("Threadgroup/Imageblock Store Limiter", 0)
+ tg_ld_lim = counter_dict.get("Threadgroup/Imageblock Load Limiter", 0)
tg_st = counter_dict.get("Threadgroup/Imageblock Store Utilization", 0)
- row = f" TGroup: LdLim {tg_ld_lim:>5.1f}% Load {tg_ld:>5.1f}% StLim {tg_st_lim:>5.1f}% Store {tg_st:>5.1f}%"
- print("│" + row.ljust(78) + "│")
+ tg_st_lim = counter_dict.get("Threadgroup/Imageblock Store Limiter", 0)
+ table.add_row(
+ "Threadgroup",
+ f"Load {tg_ld:>5.1f}% (lim {tg_ld_lim:>5.1f}%) Store {tg_st:>5.1f}% (lim {tg_st_lim:>5.1f}%)",
+ )
compute_occ = counter_dict.get("Compute Occupancy", 0)
- mmu_lim = counter_dict.get("MMU Limiter", 0)
mmu_util = counter_dict.get("MMU Utilization", 0)
- row = f" Occup: Compute {compute_occ:>5.1f}% MMU Lim {mmu_lim:>5.1f}% Util {mmu_util:>5.1f}%"
- print("│" + row.ljust(78) + "│")
+ mmu_lim = counter_dict.get("MMU Limiter", 0)
+ table.add_row(
+ "Occupancy",
+ f"Compute [green]{compute_occ:>5.1f}%[/] MMU {mmu_util:>5.1f}% (lim {mmu_lim:>5.1f}%)",
+ )
bottleneck = _find_bottleneck(counter_dict)
if bottleneck:
bn_name, bn_value = bottleneck
- row = f" >>> Bottleneck: {bn_name} ({bn_value:.1f}%)"
- print("│" + row.ljust(78) + "│")
+ table.add_row(
+ "[red]⚠ Bottleneck[/]", f"[red bold]{bn_name} ({bn_value:.1f}%)[/]"
+ )
- print("└" + "─" * 78 + "┘")
+ console.print(table)
def print_summary(export: TraceExport, verbose: bool = False) -> None:
meta = export.metadata
util = export.utilization
- print()
- print("┌" + "─" * 78 + "┐")
- print("│" + " GPU TRACE SUMMARY ".center(78) + "│")
- print("├" + "─" * 78 + "┤")
-
- print("│" + f" Device: {meta.device_model} ({meta.device_name})".ljust(78) + "│")
- print("│" + f" OS: {meta.os_version}".ljust(78) + "│")
- print(
- "│"
- + f" Process: {meta.target_process} (PID {meta.target_pid})".ljust(78)
- + "│"
- )
- print("│" + f" Template: {meta.template_name}".ljust(78) + "│")
- print("│" + f" Duration: {_fmt_ns(util.run_duration_ns)}".ljust(78) + "│")
-
- print("├" + "─" * 78 + "┤")
- print("│" + " UTILIZATION ".center(78) + "│")
- print("├" + "─" * 78 + "┤")
+ # Device info
+ device_table = Table(title="[bold]GPU Trace Summary[/]", box=box.ROUNDED)
+ device_table.add_column("Property", style="dim")
+ device_table.add_column("Value", style="green")
+ device_table.add_row("Device", f"{meta.device_model} ({meta.device_name})")
+ device_table.add_row("OS", meta.os_version)
+ device_table.add_row("Process", f"{meta.target_process} (PID {meta.target_pid})")
+ device_table.add_row("Template", meta.template_name)
+ device_table.add_row("Duration", _fmt_ns(util.run_duration_ns))
+ console.print(device_table)
+ console.print()
+
+ # Utilization
+ util_table = Table(title="[bold green]◉ Utilization[/]", box=box.ROUNDED)
+ util_table.add_column("Metric", style="dim")
+ util_table.add_column("Bar", min_width=22)
+ util_table.add_column("Value", justify="right")
+ util_table.add_column("Time", style="dim")
global_pct = util.global_utilization_percent
target_pct = util.target_utilization_percent
window_pct = util.window_utilization_percent
- print(
- "│"
- + f" Global GPU Active: {_bar(global_pct)} {_fmt_percent(global_pct):>8} ({_fmt_ns(util.global_active_ns)})".ljust(
- 78
- )
- + "│"
+ g_val, g_color = _color_percent(global_pct)
+ t_val, t_color = _color_percent(target_pct)
+ w_val, w_color = _color_percent(window_pct)
+
+ util_table.add_row(
+ "Global GPU Active",
+ _bar(global_pct),
+ f"[{g_color}]{g_val}[/]",
+ _fmt_ns(util.global_active_ns),
)
- print(
- "│"
- + f" Target GPU Active: {_bar(target_pct)} {_fmt_percent(target_pct):>8} ({_fmt_ns(util.target_active_ns)})".ljust(
- 78
- )
- + "│"
+ util_table.add_row(
+ "Target GPU Active",
+ _bar(target_pct),
+ f"[{t_color}]{t_val}[/]",
+ _fmt_ns(util.target_active_ns),
)
- print(
- "│"
- + f" Window Utilization: {_bar(window_pct)} {_fmt_percent(window_pct):>8} (when active)".ljust(
- 78
- )
- + "│"
+ util_table.add_row(
+ "Window Util (peak)", _bar(window_pct), f"[{w_color}]{w_val}[/]", "when active"
)
- print("│" + f" Command Buffers: {util.command_buffer_count}".ljust(78) + "│")
+ util_table.add_row(
+ "Command Buffers", "", f"[cyan]{util.command_buffer_count}[/]", ""
+ )
+ console.print(util_table)
+ console.print()
+ # Performance states
if export.performance_states:
states: dict[str, int] = {}
for ps in export.performance_states:
key = ps.state.value
states[key] = states.get(key, 0) + ps.duration_ns
induced_count = sum(1 for ps in export.performance_states if ps.is_induced)
- print("├" + "─" * 78 + "┤")
- print("│" + " GPU PERFORMANCE STATES ".center(78) + "│")
- print("├" + "─" * 78 + "┤")
+
+ ps_table = Table(title="[bold]GPU Performance States[/]", box=box.ROUNDED)
+ ps_table.add_column("State", style="yellow")
+ ps_table.add_column("Duration", justify="right", style="green")
for state_name, duration in sorted(states.items(), key=lambda x: -x[1]):
- print("│" + f" {state_name}: {_fmt_ns(duration)}".ljust(78) + "│")
+ ps_table.add_row(state_name, _fmt_ns(duration))
if induced_count:
- print(
- "│" + f" ⚠ Induced states: {induced_count} intervals".ljust(78) + "│"
+ ps_table.add_row(
+ "[dim]⚠ Induced states[/]", f"[dim]{induced_count} intervals[/]"
)
+ console.print(ps_table)
+ console.print()
+ # Counters available
if export.counter_definitions:
- print("├" + "─" * 78 + "┤")
- print("│" + " AVAILABLE COUNTERS ".center(78) + "│")
- print("├" + "─" * 78 + "┤")
- print(
- "│"
- + f" {len(export.counter_definitions)} GPU hardware counters available".ljust(
- 78
- )
- + "│"
+ console.print(
+ f"[dim]{len(export.counter_definitions)} GPU hardware counters available[/]"
)
+ console.print()
- print("├" + "─" * 78 + "┤")
- print("│" + " KERNEL DISPATCHES ".center(78) + "│")
- print("├" + "─" * 78 + "┤")
- print("│" + f" Total dispatches: {len(export.dispatches):,}".ljust(78) + "│")
- print("│" + f" Unique kernels: {len(export.kernel_summary)}".ljust(78) + "│")
- print("│" + f" Shaders compiled: {len(export.shaders)}".ljust(78) + "│")
+ # Dispatch summary
+ console.print(
+ f"[bold]Kernel Dispatches:[/] {len(export.dispatches):,} total, {len(export.kernel_summary)} unique, {len(export.shaders)} shaders compiled"
+ )
+ console.print()
+ # Top kernels by time
if export.kernel_summary:
- print("├" + "─" * 78 + "┤")
- print("│" + " TOP 15 KERNELS BY TIME ".center(78) + "│")
- print("├" + "─" * 78 + "┤")
- header = f" {'Kernel':<30} {'Total':>10} {'Avg':>10} {'Count':>7} {'%':>6}"
- print("│" + header.ljust(78) + "│")
- print("├" + "─" * 78 + "┤")
+ kernel_table = Table(
+ title="[bold cyan]⚡ Top 15 Kernels by Time[/]",
+ box=box.ROUNDED,
+ expand=False,
+ )
+ kernel_table.add_column(
+ "Kernel",
+ style="white",
+ min_width=40,
+ max_width=50,
+ no_wrap=True,
+ overflow="ellipsis",
+ )
+ kernel_table.add_column(
+ "Total", justify="right", style="green", no_wrap=True, min_width=10
+ )
+ kernel_table.add_column("Share", no_wrap=True, min_width=18)
+ kernel_table.add_column(
+ "Count", justify="right", style="dim", no_wrap=True, min_width=6
+ )
+ kernel_table.add_column(
+ "Avg", justify="right", style="cyan", no_wrap=True, min_width=10
+ )
total_ns = sum(k.total_ns for k in export.kernel_summary)
for k in export.kernel_summary[:15]:
pct = (k.total_ns / total_ns * 100) if total_ns else 0
- name = k.name[:30] if len(k.name) <= 30 else k.name[:27] + "..."
- row = f" {name:<30} {_fmt_ns(k.total_ns):>10} {_fmt_ns(int(k.avg_ns)):>10} {k.count:>7} {pct:>5.1f}%"
- print("│" + row.ljust(78) + "│")
+ bar = _bar(pct * 2, width=8) # scale up for visibility
+ kernel_table.add_row(
+ k.name,
+ _fmt_ns(k.total_ns),
+ f"{bar} {pct:>5.1f}%",
+ str(k.count),
+ _fmt_ns(int(k.avg_ns)),
+ )
+ console.print(kernel_table)
+ console.print()
+ # Kernel counter stats
if export.kernel_counter_stats:
if verbose:
- print("├" + "─" * 78 + "┤")
- print("│" + " TOP 10 KERNELS - DETAILED COUNTERS ".center(78) + "│")
- print("└" + "─" * 78 + "┘")
- print()
+ console.print(
+ Panel(
+ "[bold magenta]📊 Top 10 Kernels - Detailed HW Counters[/]",
+ box=box.ROUNDED,
+ )
+ )
+ console.print()
for kcs in export.kernel_counter_stats[:10]:
if kcs.counters:
_print_kernel_detail(kcs)
- print()
- return
+ console.print()
else:
- print("├" + "─" * 78 + "┤")
- print("│" + " TOP 10 KERNELS WITH COUNTERS ".center(78) + "│")
- print("├" + "─" * 78 + "┤")
- header = f" {'Kernel':<26} {'ALU':>8} {'BufLd':>8} {'BufSt':>8} {'Occup':>8} {'Cache':>8}"
- print("│" + header.ljust(78) + "│")
- print("├" + "─" * 78 + "┤")
+ counter_table = Table(
+ title="[bold magenta]📊 Top 10 Kernels - HW Counters[/]",
+ box=box.ROUNDED,
+ expand=False,
+ )
+ counter_table.add_column(
+ "Kernel",
+ style="white",
+ min_width=40,
+ max_width=50,
+ no_wrap=True,
+ overflow="ellipsis",
+ )
+ counter_table.add_column("ALU", justify="right", no_wrap=True, min_width=8)
+ counter_table.add_column(
+ "BufLoad", justify="right", no_wrap=True, min_width=9
+ )
+ counter_table.add_column(
+ "BufStore", justify="right", no_wrap=True, min_width=9
+ )
+ counter_table.add_column(
+ "Occupancy", justify="right", no_wrap=True, min_width=10
+ )
+ counter_table.add_column("LLC", justify="right", no_wrap=True, min_width=7)
for kcs in export.kernel_counter_stats[:10]:
if not kcs.counters:
@@ -233,16 +317,22 @@ def print_summary(export: TraceExport, verbose: bool = False) -> None:
occup = counter_dict.get("Compute Occupancy", 0)
cache = counter_dict.get("GPU Last Level Cache Utilization", 0)
- name = kcs.name[:26] if len(kcs.name) <= 26 else kcs.name[:23] + "..."
- row = f" {name:<26} {alu:>7.1f}% {buf_ld:>7.1f}% {buf_st:>7.1f}% {occup:>7.1f}% {cache:>7.1f}%"
- print("│" + row.ljust(78) + "│")
-
- print("└" + "─" * 78 + "┘")
- print()
- return
+ a_val, a_col = _color_percent(alu)
+ bl_val, bl_col = _color_percent(buf_ld)
+ bs_val, bs_col = _color_percent(buf_st)
+ o_val, o_col = _color_percent(occup)
+ c_val, c_col = _color_percent(cache)
- print("└" + "─" * 78 + "┘")
- print()
+ counter_table.add_row(
+ kcs.name,
+ f"[{a_col}]{a_val}[/]",
+ f"[{bl_col}]{bl_val}[/]",
+ f"[{bs_col}]{bs_val}[/]",
+ f"[{o_col}]{o_val}[/]",
+ f"[{c_col}]{c_val}[/]",
+ )
+ console.print(counter_table)
+ console.print()
def print_comparison(
@@ -251,31 +341,29 @@ def print_comparison(
label1: str,
label2: str,
) -> None:
- print()
- print("┌" + "─" * 78 + "┐")
- print("│" + " GPU TRACE COMPARISON ".center(78) + "│")
- print("├" + "─" * 78 + "┤")
-
- print("│" + f" {label1}: {export1.metadata.target_process}".ljust(78) + "│")
- print("│" + f" {label2}: {export2.metadata.target_process}".ljust(78) + "│")
-
- print("├" + "─" * 78 + "┤")
- print("│" + " UTILIZATION ".center(78) + "│")
- print("├" + "─" * 78 + "┤")
-
- header = f" {'Metric':<22} {label1:>14} {label2:>14} {'Diff':>14}"
- print("│" + header.ljust(78) + "│")
- print("├" + "─" * 78 + "┤")
+ console.print()
+ console.print(
+ Panel(f"[bold]GPU Trace Comparison[/]\n{label1} vs {label2}", box=box.ROUNDED)
+ )
+ console.print()
- def _diff_str(v1: float, v2: float) -> str:
+ def _diff_str(v1: float, v2: float) -> tuple[str, str]:
if v1 == 0:
- return "n/a"
+ return "n/a", "dim"
diff = (v2 - v1) / v1 * 100
sign = "+" if diff >= 0 else ""
- return f"{sign}{diff:.1f}%"
+ color = "red" if diff > 0 else "green" if diff < 0 else "dim"
+ return f"{sign}{diff:.1f}%", color
u1, u2 = export1.utilization, export2.utilization
+ # Utilization comparison
+ util_table = Table(title="[bold]Utilization Comparison[/]", box=box.ROUNDED)
+ util_table.add_column("Metric", style="dim")
+ util_table.add_column(label1, justify="right", style="cyan")
+ util_table.add_column(label2, justify="right", style="cyan")
+ util_table.add_column("Diff", justify="right")
+
rows = [
(
"Duration",
@@ -297,23 +385,25 @@ def print_comparison(
),
]
- for metric, v1, v2, diff in rows:
- row = f" {metric:<22} {v1:>14} {v2:>14} {diff:>14}"
- print("│" + row.ljust(78) + "│")
-
- print("├" + "─" * 78 + "┤")
- print("│" + " TOP KERNELS COMPARISON ".center(78) + "│")
- print("├" + "─" * 78 + "┤")
+ for metric, v1, v2, (diff, color) in rows:
+ util_table.add_row(metric, v1, v2, f"[{color}]{diff}[/]")
+ console.print(util_table)
+ console.print()
- header = f" {'Kernel':<32} {label1:>12} {label2:>12} {'Diff':>10}"
- print("│" + header.ljust(78) + "│")
- print("├" + "─" * 78 + "┤")
+ # Kernel comparison
+ kernel_table = Table(title="[bold]Top Kernels Comparison[/]", box=box.ROUNDED)
+ kernel_table.add_column(
+ "Kernel", style="white", max_width=40, no_wrap=True, overflow="ellipsis"
+ )
+ kernel_table.add_column(label1, justify="right", style="cyan")
+ kernel_table.add_column(label2, justify="right", style="cyan")
+ kernel_table.add_column("Diff", justify="right")
kernel_map1 = {k.name: k for k in export1.kernel_summary}
kernel_map2 = {k.name: k for k in export2.kernel_summary}
all_names = set(kernel_map1.keys()) | set(kernel_map2.keys())
- combined: list[tuple[str, int, int, str]] = []
+ combined: list[tuple[str, int, int, tuple[str, str]]] = []
for name in all_names:
k1 = kernel_map1.get(name)
k2 = kernel_map2.get(name)
@@ -324,17 +414,18 @@ def print_comparison(
combined.sort(key=lambda x: x[1] + x[2], reverse=True)
- for name, ns1, ns2, diff in combined[:15]:
- short_name = name[:32] if len(name) <= 32 else name[:29] + "..."
- row = f" {short_name:<32} {_fmt_ns(ns1):>12} {_fmt_ns(ns2):>12} {diff:>10}"
- print("│" + row.ljust(78) + "│")
+ for name, ns1, ns2, (diff, color) in combined[:15]:
+ kernel_table.add_row(name, _fmt_ns(ns1), _fmt_ns(ns2), f"[{color}]{diff}[/]")
total1 = sum(k.total_ns for k in export1.kernel_summary)
total2 = sum(k.total_ns for k in export2.kernel_summary)
+ total_diff, total_color = _diff_str(total1, total2)
+ kernel_table.add_row(
+ "[bold]TOTAL[/]",
+ f"[bold]{_fmt_ns(total1)}[/]",
+ f"[bold]{_fmt_ns(total2)}[/]",
+ f"[bold {total_color}]{total_diff}[/]",
+ )
- print("├" + "─" * 78 + "┤")
- row = f" {'TOTAL':<32} {_fmt_ns(total1):>12} {_fmt_ns(total2):>12} {_diff_str(total1, total2):>10}"
- print("│" + row.ljust(78) + "│")
-
- print("└" + "─" * 78 + "┘")
- print()
+ console.print(kernel_table)
+ console.print()
diff --git a/tools/gpu_trace/src/gpu_trace/main.py b/tools/gpu_trace/src/gpu_trace/main.py
index 717720769..c898fd0f8 100644
--- a/tools/gpu_trace/src/gpu_trace/main.py
+++ b/tools/gpu_trace/src/gpu_trace/main.py
@@ -19,7 +19,7 @@ from .formatting import print_comparison, print_summary
from .models import TraceExport
from .progress import status
from .recorder import default_output_path, record_trace
-from .serialization import to_json
+from .serialization import from_json, to_json
def export_trace(trace: Path, run_number: int) -> TraceExport:
@@ -138,6 +138,22 @@ def cmd_compare(args: argparse.Namespace) -> int:
return 0
+def cmd_view(args: argparse.Namespace) -> int:
+ json_path = args.json_file
+ if not json_path.exists():
+ print(f"Error: JSON file not found: {json_path}", file=sys.stderr)
+ return 1
+
+ try:
+ export = from_json(json_path.read_text())
+ except Exception as e:
+ print(f"Error: Failed to parse JSON: {e}", file=sys.stderr)
+ return 1
+
+ print_summary(export, verbose=args.verbose)
+ return 0
+
+
MAIN_DESCRIPTION = """
Metal GPU Trace Tool - Profile GPU performance on macOS.
@@ -233,6 +249,22 @@ Examples:
gpu_trace compare a.trace b.trace --label1 before --label2 after
"""
+VIEW_DESCRIPTION = """
+Visualize a previously exported JSON trace file.
+
+Displays the same summary tables as 'analyze' but from a JSON export,
+allowing offline viewing without the original .trace bundle.
+""".strip()
+
+VIEW_EPILOG = """
+Examples:
+ # View exported JSON
+ gpu_trace view output.json
+
+ # Verbose output with all counters
+ gpu_trace view output.json -v
+"""
+
def main(argv: list[str]) -> int:
parser = argparse.ArgumentParser(
@@ -383,6 +415,25 @@ def main(argv: list[str]) -> int:
help="Label for second trace (default: comparison)",
)
+ # --- view subcommand ---
+ view_p = sub.add_parser(
+ "view",
+ help="View a previously exported JSON trace",
+ description=VIEW_DESCRIPTION,
+ formatter_class=argparse.RawDescriptionHelpFormatter,
+ epilog=VIEW_EPILOG,
+ )
+ view_p.add_argument(
+ "json_file",
+ type=Path,
+ help="Path to JSON file exported by 'analyze --json'",
+ )
+ view_p.add_argument(
+ "-v", "--verbose",
+ action="store_true",
+ help="Show all hardware counters per kernel",
+ )
+
args = parser.parse_args(argv)
if args.cmd == "run":
@@ -391,6 +442,8 @@ def main(argv: list[str]) -> int:
return cmd_analyze(args)
elif args.cmd == "compare":
return cmd_compare(args)
+ elif args.cmd == "view":
+ return cmd_view(args)
return 1
diff --git a/tools/gpu_trace/src/gpu_trace/models.py b/tools/gpu_trace/src/gpu_trace/models.py
index 1b3ba9a57..2e8fe0485 100644
--- a/tools/gpu_trace/src/gpu_trace/models.py
+++ b/tools/gpu_trace/src/gpu_trace/models.py
@@ -149,10 +149,10 @@ class KernelCounterStats:
class TraceExport:
metadata: TraceMetadata
utilization: GpuUtilization
- performance_states: tuple[GpuPerformanceStateInterval, ...]
- counter_definitions: tuple[GpuCounterDefinition, ...]
- dispatches: tuple[KernelDispatch, ...]
- shaders: tuple[ShaderInfo, ...]
- kernel_summary: tuple[KernelStats, ...]
- counter_samples: tuple[CounterSample, ...]
- kernel_counter_stats: tuple[KernelCounterStats, ...]
+ performance_states: tuple[GpuPerformanceStateInterval, ...] = ()
+ counter_definitions: tuple[GpuCounterDefinition, ...] = ()
+ dispatches: tuple[KernelDispatch, ...] = ()
+ shaders: tuple[ShaderInfo, ...] = ()
+ kernel_summary: tuple[KernelStats, ...] = ()
+ counter_samples: tuple[CounterSample, ...] = ()
+ kernel_counter_stats: tuple[KernelCounterStats, ...] = ()
diff --git a/tools/gpu_trace/src/gpu_trace/serialization.py b/tools/gpu_trace/src/gpu_trace/serialization.py
index 618261568..b62ebd8b1 100644
--- a/tools/gpu_trace/src/gpu_trace/serialization.py
+++ b/tools/gpu_trace/src/gpu_trace/serialization.py
@@ -47,7 +47,9 @@ _converter = _make_converter()
def to_dict(export: TraceExport) -> dict[str, Any]:
- return _converter.unstructure(export)
+ data = _converter.unstructure(export)
+ data.pop("counter_samples", None)
+ return data
def to_json(export: TraceExport, indent: int | None = 2) -> str:
diff --git a/tools/gpu_trace/uv.lock b/tools/gpu_trace/uv.lock
index ab3521ade..724fe9160 100644
--- a/tools/gpu_trace/uv.lock
+++ b/tools/gpu_trace/uv.lock
@@ -30,10 +30,57 @@ version = "0.1.0"
source = { editable = "." }
dependencies = [
{ name = "cattrs" },
+ { name = "rich" },
]
[package.metadata]
-requires-dist = [{ name = "cattrs", specifier = ">=24.1.0" }]
+requires-dist = [
+ { name = "cattrs", specifier = ">=24.1.0" },
+ { name = "rich", specifier = ">=13.0.0" },
+]
+
+[[package]]
+name = "markdown-it-py"
+version = "4.0.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "mdurl" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/5b/f5/4ec618ed16cc4f8fb3b701563655a69816155e79e24a17b651541804721d/markdown_it_py-4.0.0.tar.gz", hash = "sha256:cb0a2b4aa34f932c007117b194e945bd74e0ec24133ceb5bac59009cda1cb9f3", size = 73070, upload-time = "2025-08-11T12:57:52.854Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/94/54/e7d793b573f298e1c9013b8c4dade17d481164aa517d1d7148619c2cedbf/markdown_it_py-4.0.0-py3-none-any.whl", hash = "sha256:87327c59b172c5011896038353a81343b6754500a08cd7a4973bb48c6d578147", size = 87321, upload-time = "2025-08-11T12:57:51.923Z" },
+]
+
+[[package]]
+name = "mdurl"
+version = "0.1.2"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/d6/54/cfe61301667036ec958cb99bd3efefba235e65cdeb9c84d24a8293ba1d90/mdurl-0.1.2.tar.gz", hash = "sha256:bb413d29f5eea38f31dd4754dd7377d4465116fb207585f97bf925588687c1ba", size = 8729, upload-time = "2022-08-14T12:40:10.846Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/b3/38/89ba8ad64ae25be8de66a6d463314cf1eb366222074cfda9ee839c56a4b4/mdurl-0.1.2-py3-none-any.whl", hash = "sha256:84008a41e51615a49fc9966191ff91509e3c40b939176e643fd50a5c2196b8f8", size = 9979, upload-time = "2022-08-14T12:40:09.779Z" },
+]
+
+[[package]]
+name = "pygments"
+version = "2.19.2"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/b0/77/a5b8c569bf593b0140bde72ea885a803b82086995367bf2037de0159d924/pygments-2.19.2.tar.gz", hash = "sha256:636cb2477cec7f8952536970bc533bc43743542f70392ae026374600add5b887", size = 4968631, upload-time = "2025-06-21T13:39:12.283Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/c7/21/705964c7812476f378728bdf590ca4b771ec72385c533964653c68e86bdc/pygments-2.19.2-py3-none-any.whl", hash = "sha256:86540386c03d588bb81d44bc3928634ff26449851e99741617ecb9037ee5ec0b", size = 1225217, upload-time = "2025-06-21T13:39:07.939Z" },
+]
+
+[[package]]
+name = "rich"
+version = "14.2.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "markdown-it-py" },
+ { name = "pygments" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/fb/d2/8920e102050a0de7bfabeb4c4614a49248cf8d5d7a8d01885fbb24dc767a/rich-14.2.0.tar.gz", hash = "sha256:73ff50c7c0c1c77c8243079283f4edb376f0f6442433aecb8ce7e6d0b92d1fe4", size = 219990, upload-time = "2025-10-09T14:16:53.064Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/25/7a/b0178788f8dc6cafce37a212c99565fa1fe7872c70c6c9c1e1a372d9d88f/rich-14.2.0-py3-none-any.whl", hash = "sha256:76bc51fe2e57d2b1be1f96c524b890b816e334ab4c1e45888799bfaab0021edd", size = 243393, upload-time = "2025-10-09T14:16:51.245Z" },
+]
[[package]]
name = "typing-extensions"