/pvanalyze

name: pvanalyze
description: "Use `pvanalyze` to inspect existing .NET `.nettrace` files from the command line, including GC, JIT, CPU stacks, allocation, DATAS, events, exceptions, timeline, and call-tree analysis with JSON or SpeedScope. USE FOR: the user mentions pvanalyze, PerfView-style CLI trace analysis, or cross-platform .nettrace inspection; the task starts from an existing .nettrace file and needs. DO NOT USE FOR: unrelated stacks; generic tasks that do not need this specific guidance. INVOKES: inspect the repository context, edit targeted files, and run relevant build, test, lint, or validation commands when changes are made."
compatibility: "Requires .NET 8 or later to run `pvanalyze`; trace collection usually requires `dotnet-trace`. Some scenarios require traces captured with verbose runtime providers or .NET 9+ DATAS events."

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

4. Prefer `--format json` when another tool or agent will consume the output. 5. Add `--from` and `--to` only after the baseline command confirms the interesting time window. 6. 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:

# .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:

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:

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

Practical Usage

Read trace metadata and GC signal

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

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

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:

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

Allocation analysis requires allocation events:

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:

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>`,