pvanalyze

Trigger On

• the user mentions pvanalyze, PerfView-style CLI trace analysis, or cross-platform .nettrace inspection
• the task starts from an existing .nettrace file and needs readable terminal or JSON output
• an agent or CI workflow needs GC, JIT, CPU stack, allocation, event, exception, timeline, or call-tree summaries
• SpeedScope export is useful but the source artifact is a .nettrace

Use dotnet-trace-collect or profiling first when the task is mostly about collecting the trace. Use pvanalyze once a trace artifact exists or when the user wants the specific command surface.

Workflow

1. Confirm the trace path and whether it was collected with the events needed for the question.
2. Run pvanalyze info <trace.nettrace> first to verify the file opens and contains the expected processes.
3. Pick one focused analysis command:

• gcstats for GC count, heap size, pause, and GC timeline questions
• alloc for allocation-by-type questions
• datas for Dynamic Adaptation To Application Sizes heap-count tuning
• jitstats for JIT compilation cost
• cpustacks for top CPU methods, module grouping, namespace grouping, or SpeedScope export
• calltree for hot paths and caller/callee exploration
• events for provider, event type, payload, PID, or TID filtering
• exceptions for thrown exception summaries and details
• timeline or snapshot when an agent needs time-bucketed context

1. Prefer --format json when another tool or agent will consume the output.
2. Add --from and --to only after the baseline command confirms the interesting time window.
3. Use pvanalyze clean <trace-or-directory> when generated .pvanalyze.etlx cache files should be removed.

Current Upstream Notes

• The upstream README still positions pvanalyze as a cross-platform .nettrace analyzer and explicitly says --help plus the README are the intended agent context rather than a separate upstream SKILL.md or AGENTS.md.
• Keep this catalog skill focused on practical command selection and trace prerequisites. Do not add pvanalyze as a broad diagnostics replacement for trace collection, counters, dumps, or Microsoft-only tooling.

Install

The upstream README documents two install paths:

bash
# .NET 10+ one-shot execution path
dnx pvanalyze

# Global tool path
dotnet tool install --global pvanalyze

If the NuGet package is not resolvable in the current environment, build or pack from source:

bash
git clone https://github.com/adityamandaleeka/pvanalyze
cd pvanalyze
dotnet build -c Release
dotnet run -c Release -- info ./trace.nettrace

The source project is configured as a .NET tool with PackageId pvanalyze, ToolCommandName pvanalyze, and VersionPrefix 0.1.0.

Install trace collection support when you need to create the input artifact:

bash
dotnet tool install --global dotnet-trace
dotnet-trace --version
pvanalyze --help

Practical Usage

Read trace metadata and GC signal

bash
pvanalyze info ./trace.nettrace
pvanalyze gcstats ./trace.nettrace --format json
pvanalyze gcstats ./trace.nettrace --timeline --longest 5
pvanalyze gcstats ./trace.nettrace --from 1000 --to 2000 --timeline --format json

Write CPU outputs for review

bash
pvanalyze cpustacks ./trace.nettrace --top 20
pvanalyze cpustacks ./trace.nettrace --group-by module --top 10 --format json
pvanalyze cpustacks ./trace.nettrace --format speedscope --output ./trace.speedscope.json

Drill into events, exceptions, and call trees

bash
pvanalyze events ./trace.nettrace --list --format json
pvanalyze events ./trace.nettrace --provider DotNETRuntime --type GCStart --limit 50
pvanalyze exceptions ./trace.nettrace --type NullReference --format json
pvanalyze calltree ./trace.nettrace --hot-path --depth 5 --format json
pvanalyze calltree ./trace.nettrace --caller-callee "Serialize"

Collect traces with required event detail

General trace:

bash
dotnet-trace collect --process-id <PID> --output ./trace.nettrace
dotnet-trace collect -- dotnet run -c Release

Allocation analysis requires allocation events:

bash
dotnet-trace collect --providers "Microsoft-Windows-DotNETRuntime:0x200001:5" -- dotnet run -c Release
pvanalyze alloc ./trace.nettrace --group-by type --top 20 --format json

DATAS analysis requires .NET 9+ DATAS events and verbose GC runtime events:

bash
DOTNET_GCDynamicAdaptationMode=1 dotnet-trace collect -p <PID> --providers "Microsoft-Windows-DotNETRuntime:0x4C14FCCBD:5"
pvanalyze datas ./trace.nettrace --changes-only --format json

Option Patterns

• Use --process <name> on gcstats, jitstats, alloc, or datas when a trace includes multiple .NET processes.
• Use --from <ms> and --to <ms> for GC, CPU, allocation, event, exception, timeline, and call-tree time windows.
• Use --format json for automation and --format text for human terminal review.
• Use cpustacks --group-by method|module|namespace and --inclusive to change CPU aggregation.
• Use calltree --hot-path, --caller-callee <method>, --depth <n>, and --min-percent <n> to keep stack output focused.
• Use timeline --lanes gc,cpu,exceptions,alloc,jit,events --buckets <n> for a compact multi-signal view.
• Use snapshot --at <ms> --window <ms> when the question is "what was happening around this timestamp?"

Constraints

• pvanalyze analyzes trace artifacts; it does not replace dotnet-trace for collection.
• CPU stacks, allocations, DATAS, exceptions, and event filters only work when the trace contains the required events.
• The tool converts .nettrace to a sibling .pvanalyze.etlx cache for repeated reads; this is useful but can surprise clean working directories.
• SpeedScope output comes from cpustacks; use SpeedScope or another viewer for interactive flame graph inspection.
• The source currently targets net8.0; the README also documents dnx pvanalyze as a .NET 10+ path.
• If the global tool package is not available yet, use the source build path and record that in the investigation notes.

Deliver

• the exact dotnet-trace collect command used or needed to capture the right events
• the focused pvanalyze command and output format
• the relevant process, time window, provider, event type, or method filter
• any generated files such as .speedscope.json or .pvanalyze.etlx cache paths that matter for follow-up

Validate

• pvanalyze --help or dotnet run -c Release -- --help succeeds
• dotnet-trace --version succeeds when collection is part of the workflow
• pvanalyze info <trace.nettrace> reads the trace before deeper analysis begins
• JSON output parses when --format json is used
• pvanalyze clean <trace-or-directory> removes cache files when cache cleanup is required

References

• overview.md - source links, installation model, and tool positioning
• commands.md - command matrix, collection recipes, and option selection