The short version: use flamegraphs when the question is aggregate
A timeline is best when you need to know what happened at 14:03. A semantic flamegraph is better when the question is “where did the budget go across this set of sessions?” or “which task families touched the most files?” agentpprof merges operations with the same semantic stack, so repeated behavior becomes wider instead of remaining thousands of isolated events. The chart is a projection over agent activity; it does not claim that natural-language intent is a literal function-call stack.
The current implementation is also independent from AgentSight's live Linux capture path. It reads agent-native history through the agent-session parser and does not load eBPF probes or require root. That distinction matters on macOS and Windows and when you want to profile an existing Codex or Claude Code history without re-running the workload.
Start with a frozen input set if you want a reproducible result
By default, agentpprof --project-root scans recent local Codex and Claude Code sessions matching the project. That is convenient for exploration, but the input set can change as new sessions appear. A publishable comparison should name the project revision and pass explicit --session-file inputs so a second reviewer can run the same source set later.
$ agentpprof --project-root /work/repo --session-file ~/.codex/sessions/.../session.jsonl --session-file ~/.claude/projects/.../session.jsonl --view tokens -o tokens.svg
$ agentpprof --project-root /work/repo --session-file ~/.codex/sessions/.../session.jsonl --view time -o time.svgRecord the AgentSight version, session filenames or stable session identifiers, project revision, selected view, tag rules, stack definition, filters, and output format with the artifact. Without those inputs, two charts with the same title may be profiling different data.
Five views share a stack model but use different units
Width has no universal meaning. The current extension exposes five projections, and the same semantic path can be wide in one view and narrow in another. Choose the view before looking for a hotspot.
| View | Width means | Question it answers | Important caveat |
|---|---|---|---|
operations | One count per prompt, tool, or LLM operation | Which semantic paths occur most often? | Frequency is not cost or importance. |
tokens | Reported token count, otherwise a bounded text estimate | Where did model budget accumulate? | Source accounting varies; unsafe huge estimates become unknown=1. |
time | Seconds between successive timestamped events | Which activities occupy wall-clock intervals? | It is not sampled CPU time and concurrent work can overlap conceptually. |
files | File/path effect count | Which semantic paths touch the most paths? | A count does not tell you whether an effect was necessary or risky. |
network | Network/domain effect count | Which tasks are associated with external destinations? | Destination frequency is not payload volume or security severity. |
The default stack is a semantic field projection
Current agentpprof operations are field bags. The default stack is task → skill → phase → action → object → repeat → result → outcome, with an additional token frame in the tokens view. project, agent, and session remain pprof sample labels rather than default frames, so go tool pprof -tags can group them without making every visual stack deeper.
This model is intentionally configurable. --op-map or --op-map-file derives or rewrites operation fields, --where filters after mapping, and --stack plus --stack-rule selects the hierarchy shown in the output. A useful analysis states these transformations because they change which paths merge.
$ agentpprof --project-root . --op-map 'task:verify=(?i)cmd=cargo|effect=test' --where 'task=verify' --stack task,action,result,object --view operations -o verify.foldedTagging quality is part of the measurement method
Raw prompts are poor frame names: they are long, multilingual, non-deterministic, and often sensitive. agentpprof therefore attaches semantic tags. The deterministic path uses ordered regex rules; an LLM tagger and an experimental clustering path can help discover categories, but a published chart should retain the exact rules or tag cache that produced its labels.
The shipped AgentSight flamegraph skill gives operational checks for iterative rule development: drive unmatched prompts, sessions, and LLM calls below 5%; aim for roughly 10–20 categories; keep the largest category below 40% and the top three below 70%; and inspect normalized entropy and unmatched samples. These are workflow heuristics for catching obviously coarse or incomplete taxonomies, not statistical confidence guarantees.
$ agentpprof --project-root . --tagger regex --tag-rule 'prompt:review=(?i)review|diff|regression' --tag-rule 'prompt:debug=(?i)fix|bug|error|broken' --view tokens -o tagged.json --format jsonToken width has a deliberate failure mode
Token profiles prefer counts reported by the source agent. When those are unavailable, the current implementation can use bounded text estimates. Very large unsafe estimates are recorded as unknown=1 rather than allowed to dominate the profile. That behavior is worth preserving in any downstream analysis: a wide token bar should be traceable to a reported or bounded source, not silently interpreted as an exact provider bill.
For cost comparisons, also separate input, output, and cache-related token kinds when the source exposes them. “Tokens” is an accounting dimension, not a currency conversion; provider pricing, cache discounts, and model-specific billing belong in a separate calculation with their own dated price source.
Output format changes what can leak
pprof protobuf and folded stacks are useful for tooling; SVG is a self-contained visual artifact; JSON adds redacted session summaries and the stack table. Current agentpprof groups paths outside the selected project root into stable external/* buckets so home-directory names do not have to appear in public profiles. JSON previews are different: --include-previews can include prompt, command, and LLM-output snippets and should only be used on already-sanitized sessions.
$ agentpprof --project-root . --view tokens -o tokens.pb.gz
$ agentpprof --project-root . --view time -o time.folded
$ agentpprof --project-root . --view files -o files.svg
$ agentpprof --project-root . --view network -o network.jsonA first-party example shows the format, not your workload
The AgentSight repository ships token, time, file, network, benchmark, and OSWorld-Human examples. The token image below is pinned to the same v1.0.25 product commit used by this guide. It demonstrates prefix merging and width allocation; it is not a benchmark or a claim about the distribution of another team's sessions.
For a real investigation, regenerate the chart from the bounded session set you care about. If the conclusion changes when you switch from tokens to time, that is useful information: it means model budget and elapsed time are concentrated in different parts of the workflow.
Use the flamegraph to find a category, then return to the session
Aggregation deliberately removes chronology. A wide review or debug category tells you where to look, but it does not tell you which exact command failed or why an agent repeated a step. After identifying a hotspot, filter to the relevant project, agent, session, or semantic field and inspect the original trace, AgentSight report, or timeline for the causal sequence.
This two-stage workflow is the main advantage over reading thousands of spans one by one: aggregate first to find the dominant category, then drill into the original records only where the chart says the budget or effects are concentrated.
Three common interpretation mistakes
First, do not compare widths across different views as if they share a unit. Second, do not treat a semantic tag as ground truth about intent; spot-check samples, especially vague continuation prompts and multilingual fragments. Third, do not treat a file or network count as a security verdict. The projection tells you which observed effects aggregate under a semantic path; authorization and necessity still require context from the task and source session.
The same caution applies to time. The current time view derives duration from timestamped event intervals. It is useful for locating wall-clock-heavy semantic regions, but it is not a sampled CPU profiler. Use AgentSight's runtime resource views when the question is CPU or memory behavior during a live or recorded system-level run.
A reproducible publication should include the method, not only the SVG
A reviewer should be able to answer: which sessions were included, what AgentSight version parsed them, which view and unit set width, which tag rules were used, whether operation fields were rewritten, which filters and stack frames were selected, whether previews were enabled, and which project revision the sessions refer to. Save that method next to the image or report.
If you are comparing two periods or two agents, keep the taxonomy and stack definition fixed unless the experiment is explicitly about changing them. Otherwise a visual difference can come from the classification method rather than the agent behavior.