Pvanalyze

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

pvanalyze Commands

Baseline

pvanalyze --help
pvanalyze info ./trace.nettrace

GC

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

Use for pause time, heap size, generation distribution, and per-GC timelines.

JIT

pvanalyze jitstats ./trace.nettrace
pvanalyze jitstats ./trace.nettrace --process MyApp --format json

Use for method compilation count, JIT CPU time, IL size, and native size signals.

CPU Stacks

pvanalyze cpustacks ./trace.nettrace --top 20
pvanalyze cpustacks ./trace.nettrace --group-by module --top 10
pvanalyze cpustacks ./trace.nettrace --group-by namespace --inclusive
pvanalyze cpustacks ./trace.nettrace --from 1000 --to 2000 --top 10
pvanalyze cpustacks ./trace.nettrace --format json
pvanalyze cpustacks ./trace.nettrace --format speedscope --output ./trace.speedscope.json

Use --inclusive when parent cost matters more than leaf-frame self cost.

Call Tree

pvanalyze calltree ./trace.nettrace --depth 5
pvanalyze calltree ./trace.nettrace --hot-path
pvanalyze calltree ./trace.nettrace --caller-callee "Serialize"
pvanalyze calltree ./trace.nettrace --hot-path --format json
pvanalyze calltree ./trace.nettrace --min-percent 2 --depth 6

Use --hot-path for the dominant chain and --caller-callee for one method substring.

Allocation

Collect allocation events first:

dotnet-trace collect --providers "Microsoft-Windows-DotNETRuntime:0x200001:5" -- dotnet run -c Release

Analyze:

pvanalyze alloc ./trace.nettrace --top 20
pvanalyze alloc ./trace.nettrace --group-by namespace --format json
pvanalyze alloc ./trace.nettrace --group-by module --from 1000 --to 2000

Use for top allocating types, LOH detection, and namespace or module-level allocation summaries.

DATAS

Collect .NET 9+ DATAS signals:

DOTNET_GCDynamicAdaptationMode=1 dotnet-trace collect -p <PID> --providers "Microsoft-Windows-DotNETRuntime:0x4C14FCCBD:5"

Analyze:

pvanalyze datas ./trace.nettrace
pvanalyze datas ./trace.nettrace --changes-only
pvanalyze datas ./trace.nettrace --samples
pvanalyze datas ./trace.nettrace --gen2
pvanalyze datas ./trace.nettrace --changes-only --format json

Use for server GC heap count, gen0 budget, tuning decisions, and gen2 full-GC backstop events.

Events

pvanalyze events ./trace.nettrace --list
pvanalyze events ./trace.nettrace --list --format json
pvanalyze events ./trace.nettrace --type GCStart
pvanalyze events ./trace.nettrace --provider DotNETRuntime --limit 50
pvanalyze events ./trace.nettrace --pid 1234
pvanalyze events ./trace.nettrace --tid 5678
pvanalyze events ./trace.nettrace --payload "ConnectionReset"
pvanalyze events ./trace.nettrace --from 500 --to 1000 --type GC

Use event listing before guessing exact event names.

Exceptions

pvanalyze exceptions ./trace.nettrace
pvanalyze exceptions ./trace.nettrace --type NullReference
pvanalyze exceptions ./trace.nettrace --limit 20 --format json
pvanalyze exceptions ./trace.nettrace --from 1000 --to 2000

Use for thrown exception count and detail. This does not replace crash dump analysis.

Timeline And Snapshot

pvanalyze timeline ./trace.nettrace
pvanalyze timeline ./trace.nettrace --lanes gc,cpu,exceptions,alloc,jit,events --buckets 80 --format json
pvanalyze snapshot ./trace.nettrace --at 1500 --window 100
pvanalyze snapshot ./trace.nettrace --at 1500 --window 250 --format json

Use these commands when an agent needs a compact cross-signal view for a time range or timestamp.

Cache Cleanup

pvanalyze clean ./trace.nettrace
pvanalyze clean ./traces/

Use after analysis when .pvanalyze.etlx cache files should not stay beside trace artifacts.

pvanalyze Overview

Official Sources

• GitHub repository: <https://github.com/adityamandaleeka/pvanalyze>
• Upstream README: <https://github.com/adityamandaleeka/pvanalyze/blob/main/README.md>
• Tool project: <https://github.com/adityamandaleeka/pvanalyze/blob/main/pvanalyze.csproj>
• Command sources: <https://github.com/adityamandaleeka/pvanalyze/tree/main/Commands>

What The Tool Is

pvanalyze is a cross-platform command-line analyzer for .NET .nettrace files. It is positioned by upstream as a PerfView companion for Mac, Linux, Windows, scripting, CI, and AI-agent workflows.

The source uses Microsoft.Diagnostics.Tracing.TraceEvent to read trace artifacts and System.CommandLine for the command surface. Repeated .nettrace reads are cached by converting to a sibling .pvanalyze.etlx file.

Install Model

The upstream README documents:

dnx pvanalyze
dotnet tool install --global pvanalyze

The source project is configured with:

• TargetFramework: net8.0
• PackAsTool: true
• ToolCommandName: pvanalyze
• PackageId: pvanalyze
• VersionPrefix: 0.1.0

If the NuGet package is not available in the current environment, clone the repository and run from source:

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

When To Choose pvanalyze

Choose pvanalyze when:

• there is already a .nettrace file
• the answer should be terminal, JSON, or SpeedScope output
• the workflow needs to run on non-Windows platforms without the PerfView GUI
• an agent needs a compact command-line trace summary

Choose lower-level official diagnostics skills when:

• the task is process discovery, live counters, dump collection, or trace provider planning
• the team needs a documented Microsoft-only toolchain
• the trace has not been collected yet and event selection is the main decision

Trace Collection Prerequisites

General trace collection:

dotnet tool install --global dotnet-trace
dotnet-trace collect --process-id <PID> --output trace.nettrace
dotnet-trace collect -- dotnet run -c Release

Allocation command support requires allocation events:

dotnet-trace collect --providers "Microsoft-Windows-DotNETRuntime:0x200001:5" -- dotnet run -c Release

DATAS command support requires .NET 9+ DATAS events:

DOTNET_GCDynamicAdaptationMode=1 dotnet-trace collect -p <PID> --providers "Microsoft-Windows-DotNETRuntime:0x4C14FCCBD:5"

Operational Notes

• pvanalyze clean removes .pvanalyze.etlx, .pvanalyze.etlx.lock, and temporary cache files.
• Use JSON output whenever output is handed to another automation step.
• Use cpustacks --format speedscope --output <file> when a flame graph viewer is needed.
• Keep the original .nettrace because replay cannot reconstruct events that were not collected.