Nsight Graphics Analyzer

Nsight Graphics 2026 Skill

Wrapper around NVIDIA Nsight Graphics 2026.1+. The agent captures GPU frames, gets 3 small JSON artifacts, and uses drill-down subcommands to answer follow-up questions without ever loading the raw 300+ MB TSV bundle.

When to use

User intents that should trigger this skill:

• "Why is this frame slow on the GPU?" / "Profile GPU performance" / "Grab a frame to inspect"
• "Capture a frame from this game" / "frame trace" / "GPU Trace"
• "What draw calls does this frame make?" / "API stream"
• "How fast does this .ngfx-capture replay?" / "replay perf"
• "Inspect markers / stages / metrics in this .ngfx-gputrace"
• "Generate a C++ capture so I can edit and replay it"

Trigger keywords: nsight, ngfx, nsight graphics, GPU trace, frame capture, frame trace, gpu profiling, frame profiling.

Quick start (90% case)

# 1. capture a 200 ms GPU Trace 30 s after launch (game must already be loaded)
python "<SKILL_DIR>/scripts/nsight.py" gputrace-capture \
  --exe "C:\Game\game.exe" --wd "C:\Game" \
  --start-after-ms 30000 --max-duration-ms 200 \
  --architecture Ada --metric-set-name "Throughput Metrics" \
  --time-every-action \
  --out "D:\captures\game.ngfx-gputrace"

# 2. the wrapper writes 3 small JSON next to the .ngfx-gputrace:
#    <session>/game.gputrace.summary.json  (~50 KB)
#    <session>/game.gputrace.stages.json   (~3  KB)
#    <session>/game.gputrace.actions.json  (~15 KB)

# 3. drill into the dominant stage from summary.json's analysis.hotspots
python "<SKILL_DIR>/scripts/nsight.py" gputrace-stages \
  "<session>/game.ngfx-gputrace" --parent "Render Camera" --top 10

Replace <SKILL_DIR> with the directory containing this SKILL.md. For any subcommand's full flag list run python scripts/nsight.py <cmd> --help.

Three rules to never break:

• GPUTRACE_REGIMES.xls is 300+ MB — never Read it directly. Drill through gputrace-stages / gputrace-actions / gputrace-metric.
• Anti-cheat games (EAC/BattlEye/Vanguard) refuse capture and exit with code 4. Try cpp-capture or disable the anti-cheat per game policy.
• If a capture fails with a permission error, re-run from an elevated PowerShell. doctor reports is_admin.

Tool layout

A single Python entry point dispatches to 25 subcommands. Full flag list for any subcommand: python "<SKILL_DIR>/scripts/nsight.py" <cmd> --help.

Exit codes: 0 success, 2 user error, 3 Nsight not found, 4 underlying tool failed, 5 wrapper-side timeout. stdout is JSON for query commands; pass --out FILE to redirect.

Parameter Decision Guide

For decisions beyond the Quick Start path — picking a start trigger, tuning trace quality vs cost, navigating drill-down after capture, or reaching for an advanced ngfx flag — Read references/parameters.md. That file contains five decision tables:

• A. User goal → command → required flags → what to read
• B. GPU Trace start trigger choice (--start-after-ms vs --start-after-frames vs --start-after-hotkey vs SDK)
• C. Trace quality vs cost trade-off (--time-every-action, --set-gpu-clocks, --real-time-shader-profiler, etc.)
• D. Drill-down workflow once the three JSON artifacts are written
• E. Advanced 1:1 ngfx flags (rare; skip unless asked)

⚠️ One red-line warning that belongs in the body, not the reference: --multi-pass-metrics is unusable through this wrapper (Nsight 2025.3 + 2026.1, verified May 2026). Combined with the mandatory --auto-export it deterministically writes an unloadable .ngfx-gputrace. The wrapper still accepts the flag for forensic / bug-report purposes but emits a runtime WARNING and returns bundle_complete=False. Full investigation in DESIGN.md → Investigations.

Capabilities-driven feature gating

The wrapper checks every conditional flag against the live ngfx install and exits with code 4 + a clear message if your build lacks that flag — preventing cryptic ngfx parse errors. Run python scripts/nsight.py capabilities to see what's available locally; wrapper_features.<key> maps each wrapper flag to its underlying ngfx flag.

Subcommand reference

Full flag list for any subcommand: python scripts/nsight.py <cmd> --help. This section is the agent-facing purpose only; flag detail lives in --help.

gputrace-capture

Wraps ngfx.exe --activity "GPU Trace Profiler" --auto-export .... Always writes <session>/<file>.ngfx-gputrace + BASE/ + 3 JSON artifacts. Use --dry-run to preview the ngfx command line.

trigger-hotkey

Synthesize a function-key press (default F11) into a target window via Win32 SendInput. Pair with gputrace-capture --start-after-hotkey run in the background to let the agent — not a human — fire the trigger once an external workflow has reached the desired scene. See the Agent-triggered capture workflow pattern below.

gputrace

Re-runs the parser pipeline against an existing trace + BASE/. Use after a skill upgrade to regenerate JSON without re-launching the game.

gputrace-stages

Stage-tree drill. --parent REGEX returns children of all matching parents grouped by name. --depth N restricts to a specific depth.

gputrace-actions

Top-N leaf markers (deepest D3DPERF_EVENTS nodes). --filter matches the leaf's own name; --in-marker matches any ancestor in the path. --with-metrics adds the headline block via one streaming REGIMES pass (~1-2 s). Important: read the definition field — actions are leaf markers, not raw draw calls.

gputrace-metric

Aggregate one metric. --name PATTERN is a regex over the metric catalog; --all-matches allows multi-match output. --in-marker REGEX returns per-marker windows in addition to the global aggregate.

Diagnostic command family (7 commands)

gputrace-stalls, gputrace-bandwidth, gputrace-shader-bound, gputrace-overdraw, gputrace-geometry, gputrace-texture-cache, gputrace-draws — focused diagnostic commands. Each returns a verdict[] array of {tag, severity, message}, severity ∈ {info, medium, high}. Thresholds are heuristics; treat verdicts as investigation starters, not absolute judgments. Most accept --in-marker REGEX to scope to a subtree (gputrace-stalls and gputrace-draws are whole-frame only).

Recommended investigation order on an unknown frame:

1. gputrace-stalls — rule out CPU-bound / pipeline-bubble first; if the GPU isn't busy, the rest of the analysis doesn't matter.
2. gputrace-bandwidth — memory-bound vs compute-bound axis.
3. Branch:
   • memory-bound → gputrace-texture-cache to localize
   • compute-bound → gputrace-shader-bound for SM utilization detail
4. gputrace-overdraw — opaque-pass quality.
5. gputrace-geometry — vertex/primitive frontend.
6. gputrace-draws — CPU-side state-churn / small-batch signals.

replay-perf

Replays a .ngfx-capture N times via ngfx-replay -n N --perf-report-dir and parses iteration_times.csv. Useful for replay-cost regression; not for original-app GPU performance (that's gputrace-capture).

How to read the artifacts