ncu-profile-analysis

Nsight Compute Profile Analysis

Use this skill for Nsight Compute .ncu-rep and zstd-compressed .ncu-repz kernel reports and kernel-internal bottleneck analysis. NCU explains why a kernel is slow internally; NSys explains what ran when. Use veloq ncu as the evidence extractor for report data, then decide whether the evidence points to occupancy, memory, scheduler, instruction, launch, or source-line work.

This skill requires the VeloQ CLI on PATH. If veloq is missing, install it before analysis.

Tool Boundary

Use veloq ncu verbs as the analysis interface. Do not parse <file>.veloq/ncu-native.json.gz, disasm cache files, or other .veloq/ artifacts directly unless the user explicitly asks for raw artifact inspection or you are developing VeloQ itself.

Detection

veloq info path/to/report.ncu-rep
veloq ncu summary --help

If veloq is missing, install it:

# Pre-built binary (Linux x86_64/aarch64, macOS x86_64/arm64)
curl -fsSL https://raw.githubusercontent.com/lucifer1004/veloq/main/scripts/install.sh | bash

# Or build from source — clone the repo first, then:
cargo build --release -p veloq

Envelope contract

JSON output is the agent contract. Success:

{
  "schema": "v1",
  "source": { "kind": "ncu", "version": "v1" },
  "command": "ncu.launches",
  "trace": { "kind": "ncu", "path": "..." },
  "data": {
    "count": 50,
    "total_matched": 1234,
    "rows": [
      /* ... */
    ],
    "auxiliary": {
      /* per-verb */
    }
  }
}

trace_span is omitted on NCU verbs (NCU reports do not carry the NSys-style primary-execution window). Every list verb returns canonical data.rows[] with a stable per-row key:

• ncu summary → one totals row (key: "totals")
• ncu launches / inspect → key = "launch:<idx>"
• ncu disasm → key = "kernel|<function_name>"; requested launch id is echoed under data.auxiliary.row_id
• ncu metrics (long form) → key = "launch:<idx>|counter:<name>"
• ncu metrics --per-launch → key = "launch:<idx>"
• ncu source-metrics --by line → key = "launch:<idx>|line:<file>:<line>"
• ncu source-metrics --by sass → key = "launch:<idx>|sass:0x<addr>"
• ncu source-metrics --by file → key = "launch:<idx>|file:<file>"
• ncu warp-stalls --by line → key = "launch:<idx>|line:<file>:<line>"
• ncu warp-stalls --by sass → key = "launch:<idx>|sass:0x<addr>"
• ncu warp-stalls --by reason → key = "launch:<idx>|reason:<stall_reason>"
• ncu sources → key = "source:<idx>"
• ncu ranges / graphs → key = "<kind>:<idx>"