Metal GPU Trace

metal-gpu-trace

Apple silicon 搭載 Mac で Wine または macOS プログラムが GPU をどのように使用するかを、コマンドラインまたは AI コーディングエージェントから測定します。フレームあたりの GPU 時間、フレームペーシング、FPS、メモリを Instruments の Metal System Trace で記録します。変換レイヤー（DXMT、Mullion、MoltenVK）が処理を短すぎるエンコーダーに分割していないか、Xcode なしで Metal の .gputrace キャプチャを読み取る方法、各 GPU ファミリーについて Apple が公開している情報を参照して数値を読み解く方法も確認できます。Python 3.9+ の標準ライブラリ、zsh、Xcode（xctrace 用）が必要です。MIT ライセンスです。Español。

ファイル	機能
perf_record.sh	Metal System Trace を使ってプログラムを N 秒間記録し、<label>_<date>.json（フレームあたりの GPU ms、フレーム間隔、FPS、Metal メモリ、常駐メモリ）と、フレームごとの CSV およびメモリ 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 で約 1 分かかります（10 秒の記録で 87 秒）。MCP サーバー経由では、記録 1 秒あたり 10 秒に 120 秒を加えた時間で呼び出し全体がタイムアウトし、時間超過した記録ではファイルが残りません。一度に実行できる記録は 1 つです。記録中は、Mac でほかの GPU 作業を行わないでください。

Wine では 30 秒間記録してください。Wine の起動時間が記録時間に含まれるためです。100 フレーム未満の記録では比較に不十分です。

ディスク使用量

各記録では JSON サマリーと 3 つの CSV が保持され、10 秒の記録で約 2 MB です（その大半は Metal のメモリサンプルです）。数十〜数百 MB の .trace は、KEEP_TRACE=1 を指定しない限り削除されます。KEEP_RUNS=N を指定すると、最新の N 件の記録だけが保持されます。

MCP サーバー

インストール

サーバーは PyPI の uvx で動作するため、クローンする必要はありません （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 にすると、呼び出しごとに出力される 1 行の stderr ログを無効にします。
KEEP_TRACE	1 にすると、trace_tables、trace_query、または Instruments 用に各記録の .trace を保持します。
KEEP_RUNS	最新の N 件の記録のみを保持します。
PERF_ENV	記録対象のプログラムに設定する NAME=VALUE の組です。区切り文字はスペースです。
PERF_INSTRUMENTS	Metal System Trace テンプレートに追加する Instruments です。区切り文字は ; です（名前は xcrun xctrace list instruments で確認できます）。各 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。最上位のキーは mcpServers ではなく servers で、サーバーには "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 prefix のすべてのプログラム、またはネイティブプログラムと同じ名前のすべてのプロセスを停止します
perf_attach	PID または名前を指定して、すでに実行中のプログラムを記録し、実行状態のままにします
perf_runs	記録を新しい順に、1 ページずつ一覧表示します。各記録の .trace が保持されているかどうかと、実行に使用した変換レイヤー（Direct3D DLL と Wine のフィンガープリント）も表示します
perf_compare	2 つの記録を比較します。主要な数値、エンコーダー、GPU のアイドル時間、各エンコーダーラベルのフレームあたりの GPU ms を、変化が大きい順に表示します。100 フレーム未満の記録にはフラグを付けます
perf_baseline	同じ記録を複数保存して名前付きのリファレンスとし、各数値の範囲を返します。引数なしの場合はリファレンスを一覧表示します
perf_baseline_record	perf_record の引数を使って同じプログラムを count 回（デフォルトは 3 回）記録し、1 回の呼び出しでその実行結果をリファレンスとして保存します
perf_check	記録をリファレンスと比較して判定します。FPS が範囲を margin_pct（デフォルトは 3）を超えて下回る、フレームあたりの GPU ms が範囲を超えて上昇する、またはフレームあたりのエンコーダー数やコマンドバッファー数が増加した場合は regressed、それ以外は improved または same と判定し、理由と比較結果全体を返します
perf_diagnose	変換レイヤーで見られるように、記録で GPU 処理が短すぎるエンコーダーに分割されているかどうかを判定します。フレームあたりのエンコーダー数とコマンドバッファー数、GPU 時間が最も長いラベル、GPU のアイドル時間を表示します
trace_tables	保持されている .trace のテーブルを、実行名またはパスを指定して一覧表示します
trace_count	保持されている .trace の複数のテーブルについて、行数を全体およびプロセスごとに数えます。デフォルトでは、変換レイヤーに関連するテーブル（GPU 間隔、エンコーダー、コンパイラーのスピル、コンパイル済みシェーダー、割り当て、カウンター、Time Profiler）が対象です。読み取る前に空のテーブルがわかります
trace_query	1 つのテーブルの行を 1 ページ分表示します。プロセスを指定することもできます
capture_summary	.gputrace の概要を表示し、calls_total のうち出現頻度の高い上位 100 件の呼び出しを一覧表示します
capture_records	.gputrace のレコードを 1 ページ分表示します
gpu_family	ファミリーまたはチップ（Apple7、M1 Pro、M3 Max）に関する Apple の情報を表示します
workload_list	workload_fetch でダウンロードできるテストプログラムを一覧表示します
workload_fetch	テストプログラムを一度だけダウンロードし、SHA-256 を検証して ~/Library/Caches/metal-gpu-trace に保持します。Claude Code は呼び出しのたびに確認を求めます

perf_record では、取得済みのテストプログラムを記録する場合、program の代わりに workload、api（mtl、d3d11、d3d12 のいずれか）、dim を指定します。最初のテストプログラムは bgfx の 17-drawstress（BSD-2、7.5 MB）です。ソースから .github/workflows/workloads.yml でビルドされます。これは立方体のグリッドで、各フレームで dim³ 回描画し、シェーダーはプログラム内に含まれています。Claude Code の compare-layer プロンプト（/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 です。これは、2026 年 5 月 21 日付の Apple の Metal Feature Set Tables、MTLGPUFamily、M3 tech talkの内容をまとめたものです。デバイスが対応しているかどうかは supportsFamily で確認できます。

MCP 仕様とClaude Code の制限への準拠状況は次のとおりです。

• 標準出力には MCP メッセージのみが出力されます。各ツール呼び出しは引数やパスを含まない1行のログを標準エラー出力に記録します（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 のドキュメントに基づき、引用ではなく言い換えています。