Skip to content

USER_GUIDE.md

Latest commit

 

History

History
154 lines (111 loc) · 6.43 KB

USER_GUIDE.md

File metadata and controls

154 lines (111 loc) · 6.43 KB
Raw

User Guide

This guide walks through every part of the LinuxPerfAdvisor interface and ends with a full worked example. It assumes the app is already running (see the quickstart); open the UI at http://localhost:5173 (dev) or the URL printed by the standalone binary.

The screen at a glance

The window is split into two columns:

  • Left column — inputs and helpers: the problem form, the output paste box, the Analyze button, the session timeline, the theme lens, and the uProf command builder.
  • Right column — results: the analysis panel, the decision map, and the skill browser.

Left column

Problem form

Source: frontend/src/components/ProblemForm.tsx

  • Describe the problem — free text, for example "p99 latency spikes on EPYC under load; IPC looks low". Keywords here help route to the right skill even when you have no profiler output yet.
  • CPU vendor — amd-epyc, intel-xeon, or leave unset. When set, results are filtered to that vendor's skills. If left unset, the vendor is auto-detected from your pasted output or problem text.
  • System context (optional) — microarchitecture (for example Zen4, SapphireRapids), NUMA configuration (NPS4, SNC2), and kernel. This context sharpens the recommendations and the LLM refine step.
  • Use LLM refine — toggle the optional OpenAI refinement. It has no effect unless an OPENAI_API_KEY is configured on the backend; the rule engine runs regardless.

Load example

Source: frontend/src/examples.ts

Four buttons paste a representative profiler output so you can try the app immediately:

Button Tool Demonstrates
perf stat (NUMA) perf-stat Low IPC with node-load-misses — NUMA locality routing
perf c2c (false sharing) perf-c2c Remote HITM / shared cache line — coherence routing
AMD uProf report uprof High L3 miss ratio and DRAM bandwidth utilization
Intel VTune summary vtune Back-end / memory bound top-down metrics

Output paste

Source: frontend/src/components/OutputPaste.tsx

Paste raw output from perf stat, perf c2c, AMDuProfCLI report, or vtune -report. The tool and vendor are detected automatically; you do not need to clean up the text first. After you analyze, the lines that matched a metric threshold are highlighted inline so you can see exactly what drove each recommendation.

Input is capped at MAX_INPUT_BYTES (256 KB by default) and is redacted of personally identifying data before any LLM call.

Analyze

Click Analyze to send the problem and pasted output to the backend. The button is disabled until you have entered a problem or some output. Once a session starts, the session id is shown next to the button.

Session timeline

Source: frontend/src/components/Timeline.tsx

Each Analyze adds a step to the timeline: the problem, the detected tool and vendor, and the top skill. This is the iterative loop — run a suggested command, paste the new output, and Analyze again to narrow the diagnosis. All steps share one session id.

Theme lens

Source: frontend/src/components/ThemeLens.tsx

A theme is a diagnostic lens — an ordered ladder of skills to work through for a class of problem (for example "Memory bandwidth" or "Tail latency / jitter"). The lens shows the ladder for the currently detected vendor, so you can follow a structured investigation rather than jumping between unrelated skills. The full set of themes is in ../backend/references/themes.md.

uProf command builder

Source: frontend/src/components/UProfBuilder.tsx

Pick a symptom or metric and CPU family (for example Zen4) and get the exact, family-gated AMDuProfCLI collect and report commands to run. This is backed by the uProf debugging database (../backend/uprof_db.json) so the commands are grounded in the AMD uProf User Guide rather than guessed.

Right column

Analysis panel

Source: frontend/src/components/AnalysisPanel.tsx

Shows the ranked recommendations. Each card includes:

  • the skill name, subsystem, and tier,
  • the evidence (which metric crossed which threshold, or which keywords matched),
  • a confidence score,
  • copy-ready run next commands,
  • the fix and verify guidance,
  • an LLM root cause and notes when refine is enabled.

Use Export report to download a Markdown summary of the problem, detected tool and vendor, recommendations with evidence, and the session timeline.

Decision map

Source: frontend/src/components/DecisionMap.tsx

A clickable table of signals grouped by subsystem. Clicking a signal appends it to the problem field, which is a fast way to steer routing toward a subsystem you suspect.

Skill browser

Source: frontend/src/components/SkillBrowser.tsx

Search and filter all 78 skills (60 AMD EPYC + 18 Intel Xeon) by name, signal, keyword, vendor, or theme. Use it to explore the catalog independently of a specific analysis.

Worked example

  1. Click perf stat (NUMA) under Load example. The paste box fills with a perf stat sample and the vendor is set accordingly.
  2. Type a problem: "low IPC under load, suspect remote memory".
  3. Click Analyze. The analysis panel ranks skills such as numa-remote near the top, with evidence pointing at the node-load-misses line, which is highlighted in the paste box.
  4. Copy a run next command (for example a perf or numactl command), run it on your machine, and paste the new output back into the box.
  5. Click Analyze again. A second step appears in the session timeline and the recommendations narrow based on the new evidence.
  6. Click Export report to save linux-perf-advisor-report.md documenting the full investigation.

Notes

  • The rule engine is deterministic and fully functional without an API key.
  • Recommendations are ranked by threshold matches and keyword overlap, ordered by theme ladder and tier; see ARCHITECTURE.md for details.
  • Vendor values must be exactly amd-epyc or intel-xeon.