ROCm docs style IA and style guide updates#50
Draft
mattwill-amd wants to merge 2 commits into
Draft
Conversation
mattwill-amd
requested review from
haofrank,
irvineoy and
sinarafati-amd
as code owners
mattwill-amd
commented
Jun 23, 2026
sinarafati-amd
previously approved these changes
Jun 23, 2026
sinarafati-amd
left a comment
sinarafati-amd
left a comment
Collaborator
There was a problem hiding this comment.
overall looks good. left some few comments to be addressed before merging
sinarafati-amd
approved these changes
Jun 26, 2026
randyh62
approved these changes
Jul 1, 2026
Comment on lines
+41
to
+43
| # Standalone gap analysis on existing traces | ||
| python -m Magpie benchmark gap-analysis --trace-dir results/benchmark_vllm_<timestamp>/ | ||
|
|
There was a problem hiding this comment.
According to Cursor, there is no gap-analysis subcommand. Magpie/main.py implements standalone gap analysis via --trace-dir on benchmark.
Suggested fix:
python -m Magpie benchmark --trace-dir results/benchmark_vllm_<timestamp>/|
|
||
| Magpie's benchmark mode runs end-to-end performance tests against LLM inference frameworks—vLLM, SGLang, and Atom—and collects throughput and latency metrics in a structured JSON report. Benchmarks can run inside a Docker container, directly on the host, or on a remote Ray cluster, and optionally capture torch profiler traces for deeper analysis with TraceLens and gap analysis. Use this mode to measure inference performance on AMD Instinct™ GPUs and identify the GPU kernels that dominate runtime. | ||
|
|
||
| Review these topics for more information: |
There was a problem hiding this comment.
Suggested change
| Review these topics for more information: | |
| For more information, see the following topics: |
|
|
||
| ## Benchmark report | ||
|
|
||
| The primary summary file is **`benchmark_report.json`** in the run workspace (see `WorkspaceManager.save_report`). It aggregates throughput, latency, and optional `gap_analysis` / `tracelens_analysis` sections. A typical shape (abbreviated, with `...` marking elided values): |
There was a problem hiding this comment.
It is not clear what "see WorkspaceManager.save_report" is directing the user to?
| } | ||
| ``` | ||
|
|
||
| ## More info |
There was a problem hiding this comment.
Not sure why we need both More Info and Related Sources.
| - [Automatic GPU selection in Magpie's benchmark mode](automatic-gpu.md) — how Magpie picks idle GPUs before launching and how to override or disable selection | ||
| - [Persistent server reuse (local) in Magpie's benchmark mode](persistent-server-reuse.md) — keep a server alive across runs to avoid model reload overhead | ||
| - [Profiling options in Magpie's benchmark mode](profiling-options.md) — configure torch profiler, TraceLens, and gap analysis | ||
| - [Analyze and compare kernels with Magpie](../analyze-compare.md) — kernel evaluation modes (orthogonal to Benchmark) |
There was a problem hiding this comment.
Suggested change
| - [Analyze and compare kernels with Magpie](../analyze-compare.md) — kernel evaluation modes (orthogonal to Benchmark) | |
| - [Analyze and compare kernels with Magpie](../analyze-compare.md) — kernel evaluation modes independent of benchmark mode |
Comment on lines
+167
to
+172
| python -m Magpie benchmark gap-analysis \ | ||
| --trace-dir results/benchmark_vllm_<timestamp>/torch_trace \ | ||
| --start-pct 50 --end-pct 80 \ | ||
| --top-k 15 \ | ||
| --categories kernel gpu \ | ||
| --ignore-categories gpu_user_annotation |
|
|
||
| # Magpie troubleshooting | ||
|
|
||
| This topic covers errors and debugging techniques. Each section presents symptoms and their solutions in a table so you can quickly find the issue you're seeing. For benchmark configuration problems not listed here, enable verbose logging with `--log-level DEBUG` and check the output before filing a bug report. |
There was a problem hiding this comment.
The api-reference.md line 29 mentions --verbose / -v for Debug logging, but the later Config settings discusses logging at line 162, but without any levels or options discussed. It is not clear from the api-reference, what the correct approach is for detailed logging for debug purposes?
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Edited and restructured docs according to our Style Guide and Diataxis information architecture guidance.