Metal GPU Trace

metal-gpu-trace

通过命令行或 AI 编码 Agent，在 Apple silicon Mac 上测量 Wine 或 macOS 程序对 GPU 的使用情况：每帧 GPU 时间、帧间隔、FPS 和内存；记录方式为 Instruments 的 Metal System Trace；检查转换层（DXMT、Mullion、MoltenVK）是否将工作拆分为过多的短编码器；无需 Xcode 即可读取 Metal .gputrace 捕获文件；以及 Apple 发布的各 GPU 系列数据，供你对照测量结果。需要 Python 3.9+ 标准库、zsh 和 Xcode（用于 xctrace）。MIT 许可证。Español。

文件	功能
perf_record.sh	使用 Metal System Trace 记录程序运行 N 秒，并写入 <label>_<date>.json（每帧 GPU 毫秒数、帧间隔、FPS、Metal 和常驻内存）以及逐帧和内存 CSV。除非设置 KEEP_TRACE=1，否则会删除之后生成的 .trace。
perf_report.py	以相同方式汇总现有的 .trace。
gputrace_read.py	无需 Xcode 即可读取 Metal .gputrace 捕获文件：命令缓冲区、编码器、绘制调用、调试组。标记为 probable 的调用名称尚未确认。
data/apple-gpu-families.json	Apple7 至 Apple10：芯片、各系列新增内容、不同的限制，以及 Apple 的来源。
metal_trace_mcp.py	基于以上所有内容的 MCP 服务。
test_metal_trace_mcp.py	无需 Instruments 即可进行自检：运行 python3 -I test_metal_trace_mcp.py 会输出 ok；pytest 会运行相同的测试。

录制

PERF_OUT=~/perf-runs zsh perf_record.sh game-d3d12 30 /path/to/wine ~/.wine /path/to/game game.exe
PERF_OUT=~/perf-runs zsh perf_record.sh app-metal 30 native - /path/to/app ./app

参数：标签、秒数、包含 bin/wine 的 Wine 目录（或 native）、Wine 前缀、工作目录、程序及其参数。若未设置 PERF_OUT，运行结果将写入 ./perf-runs。之后读取跟踪文件在 M1 Pro 上约需一分钟（录制 10 秒需 87 秒）；通过 MCP 服务调用时，每录制一秒的超时时间为 10 秒，另加 120 秒；如果录制超时，则不会留下任何文件。一次只能进行一项录制；录制期间请避免 Mac 上的其他 GPU 工作。

在 Wine 下运行时，录制 30 秒：Wine 启动会占用部分录制时间。少于 100 帧的录制太短，无法进行比较。

磁盘占用

每次录制会保留一个 JSON 摘要和三个 CSV，录制 10 秒约占 2 MB（大部分是 Metal 内存采样数据）。除非设置 KEEP_TRACE=1，否则会删除 .trace（几十到几百 MB）。KEEP_RUNS=N 仅保留最新的 N 次录制。

MCP 服务

安装

该服务通过 uvx 从 PyPI 运行，无需克隆 （brew install uv 可安装它）。录制还需要安装 Xcode（运行 xcrun xctrace version 会显示版本）。

uvx metal-gpu-trace

以下每个客户端都会运行此命令。桌面应用无法读取 Homebrew 的 PATH：请提供 which uvx 输出的完整路径（Apple 芯片设备上为 /opt/homebrew/bin/uvx）。uvx 会保留首次下载的版本；要获取最新版本，请在 uvx 后运行一次该命令并加上 --refresh。uvx [email protected] 可固定版本。

该服务会读取以下环境变量：

变量	设置内容
METAL_TRACE_OUT	录制文件的保存位置。请提供绝对路径：默认值 ./perf-runs 取决于客户端的工作目录。
METAL_TRACE_WINE	perf_record 使用的 Wine 目录（包含 bin/wine）；如果调用中未指定，则使用此目录。
WINEPREFIX	如果调用中未指定，则使用此 Wine 前缀；否则使用 ~/.wine。
METAL_TRACE_READ	工具可读取的其他目录，以 : 分隔。
METAL_TRACE_LOG	设为 off 可关闭每次调用时输出到 stderr 的单行日志。
KEEP_TRACE	设为 1 可保留每次录制的 .trace 文件，供 trace_tables、trace_query 或 Instruments 使用。
KEEP_RUNS	仅保留最新的 N 个录制文件。
PERF_ENV	为录制的程序设置的 NAME=VALUE 对，以空格分隔。
PERF_INSTRUMENTS	添加到 Metal System Trace 模板的 Instruments，以 ; 分隔（名称见 xcrun xctrace list instruments）；其表格需要 .trace 文件，因此请与 KEEP_TRACE=1 搭配使用。

Claude Code

claude mcp add --scope user metal-trace -e METAL_TRACE_OUT=$HOME/perf-runs -e METAL_TRACE_WINE=/path/to/wine \
  -- uvx metal-gpu-trace
claude mcp list

claude mcp list 会显示 metal-trace 已连接。--scope user 会使其在每个项目中都可用；省略此选项则仅将其添加到当前项目。

Claude Desktop、Cursor 和其他 JSON 客户端

这些应用不会展开 ~ 或 $HOME：请填写绝对路径。

{
  "mcpServers": {
    "metal-trace": {
      "command": "/opt/homebrew/bin/uvx",
      "args": ["metal-gpu-trace"],
      "env": {
        "METAL_TRACE_OUT": "/absolute/path/to/perf-runs",
        "METAL_TRACE_WINE": "/absolute/path/to/wine"
      }
    }
  }
}

客户端	文件
Claude Desktop	~/Library/Application Support/Claude/claude_desktop_config.json（Settings、Developer、Edit Config）；重启应用
Cursor	~/.cursor/mcp.json
VS Code	项目中的 .vscode/mcp.json；顶层键为 servers，而不是 mcpServers，并且服务需添加 "type": "stdio"

Codex CLI

在 ~/.codex/config.toml 中：

[mcp_servers.metal-trace]
command = "/opt/homebrew/bin/uvx"
args = ["metal-gpu-trace"]
env = { METAL_TRACE_OUT = "/absolute/path/to/perf-runs", METAL_TRACE_WINE = "/absolute/path/to/wine" }

工具

工具	读取或记录
perf_record	记录程序并返回摘要；结束时会停止其 Wine 前缀中的所有程序，或停止所有名称与原生程序相似的进程
perf_attach	按 PID 或名称记录已在运行的程序，并让其继续运行
perf_runs	按时间倒序逐页列出记录、每条记录是否保留了 .trace，以及运行所用的转换层（其 Direct3D DLL 和 Wine 的指纹）
perf_compare	比较两条记录：关键数据、编码器、GPU 空闲时间，以及每个编码器标签的每帧 GPU 毫秒数；变化最大者优先；标记帧数少于 100 的记录
perf_baseline	将多条相同记录保存为命名参考，并返回各项数据在这些记录中的范围；单独使用时列出参考
perf_baseline_record	使用 perf_record 的参数记录同一程序 count 次（默认 3 次），并在一次调用中将这些记录保存为参考
perf_check	根据参考评估一条记录：当 FPS 低于范围超过 margin_pct（默认 3），每帧 GPU 毫秒数高于范围，或编码器数或每帧命令缓冲区数超过范围时，判定为 regressed；否则判定为 improved 或 same，并提供原因和完整比较结果
perf_diagnose	判断一条记录是否将 GPU 工作拆分为过多的短编码器（如转换层所做的那样），并提供每帧编码器数和命令缓冲区数、GPU 时间最多的标签，以及 GPU 空闲时间
trace_tables	按运行记录名称或路径列出已保留 .trace 的表
trace_count	统计已保留 .trace 中多个表的行数，包括总数和各进程的行数；默认统计转换层相关表（GPU 间隔、编码器、编译器溢出、已编译着色器、分配、计数器、Time Profiler），以便在读取前发现空表
trace_query	查看一个表的一页行，可选指定进程
capture_summary	汇总 .gputrace；列出其 calls_total 次调用中频率最高的 100 种调用
capture_records	查看 .gputrace 记录的一页内容
gpu_family	获取 Apple 关于某个系列或芯片（Apple7、M1 Pro、M3 Max）的信息
workload_list	列出 workload_fetch 可下载的测试程序
workload_fetch	下载一次测试程序，校验其 SHA-256，并将其保存在 ~/Library/Caches/metal-gpu-trace；Claude Code 每次调用前都会询问

perf_record 使用 workload、api（mtl、d3d11 或 d3d12）和 dim，而非 program，来记录已获取的 测试程序。第一个测试程序是 bgfx 的 17-drawstress（BSD-2，7.5 MB）， 由 .github/workflows/workloads.yml 从源码构建：一个立方体网格，每帧绘制 dim³ 次，着色器包含在程序 中。compare-layer 提示词（在 Claude Code 中使用 /metal-trace:compare-layer drawstress d3d12）会在原生 Metal 和 METAL_TRACE_WINE 中指定的 Wine 下记录该程序，然后运行 perf_diagnose 和 perf_compare。

相同信息也作为 MCP 资源提供：metal-trace://gpu-families（全部系列）和 metal-trace://gpu-families/apple7 至 apple10。这些资源重述了 Apple 于 2026 年 5 月 21 日发布的 Metal Feature Set Tables、 MTLGPUFamily 和 M3 技术分享中的信息；使用 supportsFamily 检查设备。

它如何遵循 MCP 规范和 Claude Code 的限制：

• stdout 仅承载 MCP 消息；每次工具调用都会向 stderr 写入一行日志（设置 METAL_TRACE_LOG=off 可关闭），不包含参数或路径。
• 列表按页返回（offset、limit，默认 50，最多 500），并包含 total 和 next_offset；超过 40 000 个字符的结果会被拒绝，并提示请求更小的页面。
• 仅可在 METAL_TRACE_OUT 和 METAL_TRACE_READ 中列出的目录（以 : 分隔）内读取文件。
• 失败会返回说明后续操作的 isError 结果，不含堆栈跟踪或本地路径。摘要会将绝对路径缩短为文件名，方便分享。
• 每次 xctrace 调用都有超时限制。

致谢

• .gputrace 命令流的记录布局遵循 tmc/gputrace（MIT）；未复制任何代码。调用 ID 根据 macOS 27.0.1 上的 Xcode 命令列表进行了匹配。
• GPU 系列信息来自上文链接的 Apple 文档，经转述而非引用。