{"id":50725198,"url":"https://github.com/fasterthanlime/gputrace-rs","last_synced_at":"2026-06-10T03:30:47.955Z","repository":{"id":353547126,"uuid":"1219664665","full_name":"fasterthanlime/gputrace-rs","owner":"fasterthanlime","description":"A Rust port of https://github.com/tmc/gputrace/","archived":false,"fork":false,"pushed_at":"2026-05-05T18:40:21.000Z","size":1459,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-09T03:30:27.459Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fasterthanlime.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-24T05:20:03.000Z","updated_at":"2026-05-05T18:40:25.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/fasterthanlime/gputrace-rs","commit_stats":null,"previous_names":["fasterthanlime/gputrace-rs"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/fasterthanlime/gputrace-rs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fasterthanlime%2Fgputrace-rs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fasterthanlime%2Fgputrace-rs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fasterthanlime%2Fgputrace-rs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fasterthanlime%2Fgputrace-rs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fasterthanlime","download_url":"https://codeload.github.com/fasterthanlime/gputrace-rs/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fasterthanlime%2Fgputrace-rs/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34136112,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-10T02:00:07.152Z","response_time":89,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-10T03:30:47.148Z","updated_at":"2026-06-10T03:30:47.932Z","avatar_url":"https://github.com/fasterthanlime.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# gputrace-rs\n\n`gputrace` turns an existing Apple Metal `.gputrace` capture into a Markdown GPU\nperformance report.\n\nThe public workflow is one command:\n\n```bash\ngputrace report /abs/path/input.gputrace\n```\n\nIf the trace already contains cached profiler data, `report` reuses it. If not,\nit prints a line saying it is profiling, runs Apple's headless `MTLReplayer.app`,\nstores both the profiler data and the Markdown report inside the `.gputrace` bundle.\n\nInternal subcommands still exist for tests and reverse engineering, but they are\nnot part of normal use.\n\n## Install\n\n```bash\ncargo xtask install\n```\n\nThe installer builds the release binary, copies it to\n`~/.cargo/bin/gputrace`, signs the installed copy for stable macOS identity,\nand verifies `gputrace --version`.\n\n## Capture\n\n`gputrace` does not perform live capture. Your application must first create a\n`.gputrace` bundle, usually by running with Metal capture enabled.\n\nKeep captures small: one useful pulse, phase, or workload step. Profiling\nreplays the trace and can use substantial memory for large captures.\n\n## Report\n\nRun:\n\n```bash\ngputrace report /abs/path/input.gputrace\n```\n\nBy default, this writes:\n\n```text\n/abs/path/input.gputrace/gputrace-profile/input.gpuprofiler_raw/\n/abs/path/input.gputrace/gputrace-report/\n```\n\nUse `--output` only when you want the Markdown report somewhere else:\n\n```bash\ngputrace report /abs/path/input.gputrace --output /abs/path/report-dir\n```\n\nThe report directory contains Markdown files such as:\n\n```text\nindex.md\nanalysis.md\ninsights.md\ntiming.md\nshaders.md\ncounters.md\nxcode-mio.md\nprofiler.md\nprofiler-coverage.md\n```\n\nStart with `index.md`. It links the rest of the report and records parser or\nprofiler failures in one place. The command prints live progress while it runs;\n`index.md` records the total report time and per-section timings.\n\n## What The Report Means\n\nThe report combines:\n\n- `.gputrace` structure: command buffers, encoders, resources, shader names,\n  and API command topology.\n- Cached `.gpuprofiler_raw` data: MTLReplayer/Xcode profiler streams.\n- Native AGX timing analysis from `Profiling_f_*.raw`.\n- Xcode private MIO topology when available, used internally for command and\n  pipeline mapping.\n\nGPU cost percentages are estimates unless explicitly labeled as imported Xcode\nground truth. Apple does not expose the exact Xcode shader cost model as a\nstable public file format.\n\nFor source mapping, search your source tree by hot kernel names from the\nreport:\n\n```bash\nrg -n 'hot_kernel_name|another_hot_kernel' /abs/path/source/root\n```\n\n## Common Failure Modes\n\n### `report` starts profiling and then no `streamData` appears\n\nThe replay failed. Run again with MTLReplayer logs if you are debugging through\nan internal command, or capture a smaller trace. The common causes are archive\nopen failure, missing/incompatible Metal device, or GPU timeout.\n\n### GPU command-buffer timeout\n\nThe trace is usually too large or was profiled on unsuitable hardware. Capture\na smaller workload window and profile on real Apple Silicon hardware.\n\n### The report looks stale\n\nDelete the cached profiler directory and rerun `report`:\n\n```bash\nrm -rf /abs/path/input.gputrace/gputrace-profile\n\ngputrace report /abs/path/input.gputrace\n```\n\n## Internal Commands\n\nOnly `report` is public. Other subcommands are hidden from help and are for\nreport implementation, regression checks, and reverse engineering.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffasterthanlime%2Fgputrace-rs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffasterthanlime%2Fgputrace-rs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffasterthanlime%2Fgputrace-rs/lists"}