docs: complete TraceLens docs migration + consolidate the SDK analysis guide by ajassani · Pull Request #824 · AMD-AGI/TraceLens

ajassani · 2026-07-17T19:22:11Z

Summary

Completes the documentation migration by porting the remaining legacy topics from docs_original/ into the rocm-docs-core site under docs/, then reorganizing the core-feature docs so the SDK story lives in one place. Follows the conventions used across the existing pages (MyST, {meta} blocks, "Related topics", sentence-case headings, copyright headers).

Migrated pages + 3 tutorial notebooks:

Reference — perf-report-columns (full column glossary)
Concepts (new section) — trace2tree (concept-only), torch-profiling-analysis, shape-metadata, gemm-analysis (merged aimodels_gemms + gemm_dim_eff), inference-analysis (paged-attention roofline model), triton-perf-model-walkthrough
How to — sdk-analysis, perf-model-without-trace, generate-perf-report-pytorch-inference (end-to-end workflow), compare-perf-reports, nccl-analysis, origami-integration, agentic-mode
Tutorials (new section) — torch-profiling, distributed-profiling, anomaly-detection notebooks, rendered via myst-nb

Core-feature docs reorg:

how-to/sdk-analysis — new consolidated SDK guide: tree loading/traversal (TreePerfAnalyzer), GPU-timeline breakdown (GPUEventAnalyser), per-op GPU time, roofline metrics, adding a new op, and nn.Module attribution. Absorbs the former tree-perf-analysis and gpu-event-analysis how-tos.
conceptual/trace2tree — slimmed to the call-tree concept; SDK traversal how-to content moved into sdk-analysis.
how-to/perf-model-without-trace — new guide for analytical FLOPs/bytes from shapes alone (no trace).
how-to/generate-perf-report-pytorch-inference — restructured into collect → split → generate → merge, with the vLLM/SGLang build tables, profiler flags, and the steady-state split_inference_trace_annotation workflow; conceptual roofline math split out to conceptual/inference-analysis.

Infra:

_toc.yml.in and index.rst landing cards updated with Concepts, Tutorials, and the new Reference/How-to entries
rocm-docs-core bumped 1.22.0 → 1.32.0 (its built-in myst-nb renders the notebooks; execution disabled at build time via nb_execution_mode = "off")
All inbound links repointed from docs_original to the new pages (README, CODEOWNERS, API reference, agent READMEs)
CODEOWNERS — added inference-doc ownership (how-to/generate-perf-report-pytorch-inference, conceptual/inference-analysis)
docs_original/ fully retired (directory removed)
Merged latest main.

Content-fidelity check

Every example in sdk-analysis is traceable to a real source (verified against git history / source / the torch-conference poster): GPU-timeline / per-op / roofline tables from the legacy tree-perf-analysis; subtree + parent-chain examples from the legacy trace2tree; timeline metric definitions from the legacy gpu-event-analysis; the nn.Module GPU-time tree from the poster; and all SDK method names verified present in TraceLens/.

Decisions worth a look

SDK consolidation — TreePerf + GPUEventAnalyser how-tos merged into one sdk-analysis page; trace2tree kept concept-only.
Analytical perf model given its own perf-model-without-trace how-to (no trace required).
Inference split into a how-to (workflow) and a concept (roofline math).
GEMM docs merged into one conceptual/gemm-analysis page.
triton-perf-model-walkthrough placed under Concepts (explains how metrics are computed) rather than How-to.
Notebook content ported as-is; outputs preserved, not re-executed.

Validation

Read the Docs build: green on the latest push.
Lint: green.
Internal/anchor/repo-asset link check is clean (0 broken links).

Test plan

Read the Docs build succeeds with the ROCm theme
Tutorials render (myst-nb) with their captured outputs
Concepts / Tutorials / Reference nav sections appear correctly
Spot-check migrated technical content against source for accuracy

Port the remaining loose docs from docs_original into the rocm-docs-core site under docs/, following the established ROCm documentation conventions (MyST, {meta} blocks, "Related topics", sentence-case headings, copyright headers). New pages: - reference/perf-report-columns (column glossary) - conceptual/: trace2tree (merged with motivation), torch-profiling-analysis, shape-metadata, gemm-analysis (merged), perf-model-walkthrough - how-to/: tree-perf-analysis, gpu-event-analysis, compare-perf-reports, nccl-analysis, origami-integration - tutorials/: torch-profiling, distributed-profiling, anomaly-detection notebooks, rendered via myst-nb (rocm-docs-core bumped 1.22 -> 1.32, notebook execution disabled at build time) Wire the new Concepts, Tutorials, and Reference entries into _toc.yml.in and the index.rst landing cards. Repoint all inbound links (README, CODEOWNERS, API reference, agent READMEs) from docs_original to the new pages and retire the migrated docs_original files (only the deferred Agentic_Mode entry remains). Co-authored-by: Cursor <cursoragent@cursor.com>

Author a proper how-to/agentic-mode topic from the TraceLens Agent README (analysis modes, prerequisites, chat and headless CLI usage, report anatomy, workflow architecture) and wire it into the How-to nav and landing cards. Delete the last docs_original file (the deferred Agentic_Mode symlink) and the now-empty docs_original directory, completing the migration to the ROCm docs tree. The copyright regression test now passes cleanly (the Windows-only symlink false-positive is gone). Co-authored-by: Cursor <cursoragent@cursor.com>

Co-authored-by: Cursor <cursoragent@cursor.com>

…ample in collective report Co-authored-by: Cursor <cursoragent@cursor.com>

…ncepts Recover inference content that was dropped in the migration into the rendered docs: - generate-perf-report-pytorch-inference.md: restructure into an end-to-end workflow (collect -> split -> generate -> merge) with the vLLM/SGLang build tables, profiler-config flags, and the split_inference_trace_annotation steady-state workflow. - conceptual/inference-analysis.md: new page covering the paged-attention roofline model (prefill/decode FLOPS, elements moved, aggregate annotations) and the steady-state region derivation. Co-authored-by: Cursor <cursoragent@cursor.com>

…rf model guide Reorganize the core-feature docs so the SDK story lives in one place and the analytical perf model gets its own home: - how-to/sdk-analysis.md: new consolidated guide covering tree loading and traversal (TreePerfAnalyzer), GPU timeline summaries (GPUEventAnalyser), per-op GPU time, roofline metrics, and nn.Module GPU-time attribution. Absorbs the former tree-perf-analysis.md and gpu-event-analysis.md. - conceptual/trace2tree.md: slim down to the call-tree concept; SDK traversal how-to content moved to sdk-analysis.md. - how-to/perf-model-without-trace.md: new guide for computing analytical FLOPs/bytes for GEMM/SDPA ops without any trace. - Remove tree-perf-analysis.md and gpu-event-analysis.md; repoint inbound links and update the TOC. Co-authored-by: Cursor <cursoragent@cursor.com>

…o-rocm

Co-authored-by: Cursor <cursoragent@cursor.com>

…SDK-vs-report framing Co-authored-by: Cursor <cursoragent@cursor.com>

…al SDK output - Remove invented per-module GPU-time values from the nn.Module attribution diagram; show the real pretty-printer format with placeholders and defer actual numbers to the notebook. Fix the label to Non-nn.Module GPU Time. - Correct the roofline example table to the real summarize_df_perf_metrics schema (param: M/N/K/bias, FLOPS/Byte_first, TFLOPS/s_mean) using values from the legacy tree-perf doc. - Restore the parent-chain traversal example and GPU-timeline metric definitions that were dropped when the legacy docs were consolidated. Co-authored-by: Cursor <cursoragent@cursor.com>

The per-module numbers removed in the previous commit were not fabricated - they come from the published torch-conference poster (a DeepSeek-V2 decoder layer). Restore the full tree with the authoritative values and include the nodes that had been dropped (RMSNorm, ReplicatedLinear, ColumnParallelLinear, DeepseekScalingRotaryEmbedding, and the DeepseekV2MLP children). Co-authored-by: Cursor <cursoragent@cursor.com>

tsrikris

LGTM from Agent PoV

devalshahamd

Two minor comments, otherwise LGTM!

devalshahamd · 2026-07-21T00:01:00Z

+-->
+
+# Inference performance analysis in TraceLens
+```{meta}


This is rendered in the GitHub GUI. Is that expected?

Yes, expected. This is the MyST {meta} directive that Sphinx/Read the Docs turns into invisible HTML tags (description/keywords for SEO). GitHub's markdown preview doesn't process MyST directives, so it shows the raw fenced block here, but it renders correctly and invisibly on the docs site. Every migrated page uses the same block for consistency.

devalshahamd · 2026-07-21T00:14:06Z


 ## Before you begin

 Before generating a report, confirm you have the following:


I think We can remove this before you begin step since the next steps have details on how to collect traces.

Good call - trimmed in a0f999d. Dropped the trace-file bullets that duplicated the Collect and Merge sections right below, keeping only the genuine prerequisites (TraceLens installed + an inference setup).

Drop the trace-file prerequisites that duplicated the Collect and Merge sections that immediately follow; keep only the genuine prerequisites (install + an inference setup). Addresses review feedback. Co-authored-by: Cursor <cursoragent@cursor.com>

Brief specification in `compare-traces.md`. More thorough specification in `agent.md`.

Co-authored-by: Cursor <cursoragent@cursor.com>

…ff extension The comparative agent wraps TraceDiff (one of the two matching methods) rather than being a third way to compare, so revert the intro to two ways and keep the agent framed as an extension of TraceDiff. Also tidy trailing whitespace. Co-authored-by: Cursor <cursoragent@cursor.com>

Co-authored-by: Cursor <cursoragent@cursor.com>

## Summary #824 retired the `docs_original/` directory as part of the docs migration. #823 (branched before #824 and merged just after it) reintroduced a link to `docs_original/Inference_analysis.md`, which no longer exists on `main` — leaving a dead link in `TraceLens/Agent/Profiling/README.md`. This repoints that reference to the migrated how-to page and restores the descriptive link text. - `docs_original/Inference_analysis.md` (deleted) -> `docs/how-to/generate-perf-report-pytorch-inference.md` ## Test plan - [ ] Link resolves to the migrated inference how-to page Co-authored-by: Cursor <cursoragent@cursor.com>

ajassani force-pushed the docs/migrate-legacy-to-rocm branch 2 times, most recently from d982c5c to 8c85ca5 Compare July 17, 2026 20:21

ajassani and others added 4 commits July 17, 2026 17:26

Reconcile README with #817 and fix install paths after rebase

a6585d0

Co-authored-by: Cursor <cursoragent@cursor.com>

Preserve triton- prefix on perf model walkthrough doc

970f254

Co-authored-by: Cursor <cursoragent@cursor.com>

ajassani force-pushed the docs/migrate-legacy-to-rocm branch from 0dab3a8 to 970f254 Compare July 17, 2026 21:28

ajassani and others added 8 commits July 17, 2026 17:38

docs: restore all2allv spread metric, openpyxl note, and straggler ex…

73e8002

…ample in collective report Co-authored-by: Cursor <cursoragent@cursor.com>

Merge remote-tracking branch 'github/main' into docs/migrate-legacy-t…

4df1e76

…o-rocm

chore: add Deval as code owner for conceptual inference doc

b8ee315

Co-authored-by: Cursor <cursoragent@cursor.com>

docs: add roofline example table, fold add-new-op into roofline, fix …

1562f71

…SDK-vs-report framing Co-authored-by: Cursor <cursoragent@cursor.com>

ajassani marked this pull request as ready for review July 20, 2026 16:48

ajassani requested review from devalshahamd, spandoesai and tsrikris as code owners July 20, 2026 16:48

Merge branch 'main' into docs/migrate-legacy-to-rocm

e8a99bd

ajassani requested review from gabeweisz, mattwill-amd and steve-reinhardt July 20, 2026 16:49

ajassani changed the title ~~docs: migrate remaining legacy topics into the ROCm docs tree~~ docs: complete TraceLens docs migration + consolidate the SDK analysis guide Jul 20, 2026

ajassani requested a review from kyle-hoffmeyer July 20, 2026 17:08

gabeweisz approved these changes Jul 20, 2026

View reviewed changes

Align TraceLens Agent Documentation

3ca99ad

tsrikris approved these changes Jul 20, 2026

View reviewed changes

Update README.md

4bb2d16

devalshahamd reviewed Jul 21, 2026

View reviewed changes

devalshah-amd and others added 7 commits July 21, 2026 00:16

Minor edits

1c6c71e

Add brief comparative agent description to compare-traces.md (#832)

40faad8

Brief specification in `compare-traces.md`. More thorough specification in `agent.md`.

docs: fix double space in inference keywords meta

5322ac1

Co-authored-by: Cursor <cursoragent@cursor.com>

docs: replace remaining 'accelerator' with 'GPU' per ROCm style (#829)

5c8fcac

Co-authored-by: Cursor <cursoragent@cursor.com>

Merge branch 'main' into docs/migrate-legacy-to-rocm

23c04ac

ajassani merged commit d30b153 into main Jul 21, 2026
2 checks passed

ajassani deleted the docs/migrate-legacy-to-rocm branch July 21, 2026 19:02

ajassani mentioned this pull request Jul 21, 2026

docs: fix dead docs_original link in Profiling README #836

Merged

1 task

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

docs: complete TraceLens docs migration + consolidate the SDK analysis guide#824

docs: complete TraceLens docs migration + consolidate the SDK analysis guide#824
ajassani merged 22 commits into
mainfrom
docs/migrate-legacy-to-rocm

ajassani commented Jul 17, 2026 •

edited

Loading

Uh oh!

tsrikris left a comment

Uh oh!

devalshahamd left a comment

Uh oh!

devalshahamd Jul 21, 2026

Uh oh!

ajassani Jul 21, 2026

Uh oh!

devalshahamd Jul 21, 2026

Uh oh!

ajassani Jul 21, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants


		## Before you begin

		Before generating a report, confirm you have the following:

Uh oh!

Conversation

ajassani commented Jul 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Content-fidelity check

Decisions worth a look

Validation

Test plan

Uh oh!

tsrikris left a comment

Choose a reason for hiding this comment

Uh oh!

devalshahamd left a comment

Choose a reason for hiding this comment

Uh oh!

devalshahamd Jul 21, 2026

Choose a reason for hiding this comment

Uh oh!

ajassani Jul 21, 2026

Choose a reason for hiding this comment

Uh oh!

devalshahamd Jul 21, 2026

Choose a reason for hiding this comment

Uh oh!

ajassani Jul 21, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

ajassani commented Jul 17, 2026 •

edited

Loading