A semantic flamegraph is an aggregation model, not a timeline
Traditional flamegraphs merge identical call stacks and use width for CPU time. agentpprof applies the same visual idea to agent work. The default operation stack is task → skill → phase → action → object → repeat → result → outcome, with an additional token frame in the tokens view. Repeated paths merge, so a wide bar means a large share of the selected metric rather than a long chronological interval.
Choose the width metric before interpreting the chart
The operations view counts prompt/tool/LLM steps, tokens weights samples by reported token use, time weights by duration, files counts path effects, and network counts domain effects. The same semantic path can look wide in tokens and narrow in time, or wide in files and narrow in network. That is expected: each view answers a different question over the same sessions.
Keep project, agent, and session as labels unless you need them as frames
Current agentpprof keeps project, agent, and session as pprof sample labels rather than default stack frames. This keeps the visual stack focused on causal/semantic structure while still allowing filtering and grouping with pprof tooling. Add or remove stack fields with --stack when the analysis question requires a different hierarchy.
Semantic tagging is part of the analysis and must be reproducible
Free-form prompts cannot be merged reliably by raw text. agentpprof supports deterministic regex rules, an LLM tagger, and an experimental clustering backend. The documented production workflow iterates regex rules over real prompt samples until unmatched coverage and category distribution are acceptable. Save the rules or tag cache with any published analysis; otherwise another reviewer cannot reproduce the category boundaries.
Use the chart to compare categories, then return to the source sessions
A flamegraph is good at showing that review, debugging, a path family, or a network destination dominates the selected metric. It is not a substitute for the underlying session when you need the exact command or message. Drill from a wide semantic category back to the relevant runs, then use the timeline, report, process tree, or source trace to explain the specific behavior.
Do not over-read semantic categories
Tagging can misclassify vague prompts, multilingual fragments, or continuation messages. Time samples can overlap; token accounting depends on what the source agent reports; file/network views count observed effects rather than importance. Treat the chart as a profiling projection and validate surprising categories against raw samples before making budget, security, or productivity claims.
Use first-party examples as a format reference, not as your benchmark
The AgentSight repository includes token, time, file, network, benchmark, and OSWorld-Human example flamegraphs. They demonstrate how stacks merge and how different width metrics change the picture. They are not recorded data that your workload has the same distribution. Build a chart from your own bounded sessions and state the source set, tagger, rules, stack, filters, and weighting mode.
$ cargo install agentpprof
$ agentpprof --view tokens -o tokens.svg
$ agentpprof --view time -o time.svg
$ agentpprof --tagger regex --tag-rule prompt:review='(?i)review|diff|regression' -o review.svg