Part of
Bright Utils:
the b in
bgpucap is for Bright
(like btime, bfind, bping).
Run any command like time(1) and report
GPU,
CPU, and
unified memory
utilization. Crate name gpucap; CLI command
bgpucap.
bgpucap forks and execs your command, polls metrics every
100 ms (configurable with --interval), then prints a
summary to stderr. Exit status matches the child process.
bgpucap sleep 1
bgpucap --metrics basic sleep 1 # lightweight: skip extended IOReport
bgpucap --metrics gpu,pwr,freq sleep 5
bgpucap --list-metrics
bgpucap --columns --separator=' / ' sleep 1
bgpucap --pid 1234 --metrics cmd-gpu sleep 5
bgpucap --no-track-gpu sleep 1 # skip per-process GPU tracking
bgpucap --color=bright -- ffmpeg -i in.mp4 out.mp4
bgpucap --interval 50 make -j8
--metrics=LIST selects human or JSON output (default: all).
Names and groups: basic, power, freq,
thermal, mem-detail, cmd-gpu, …
Run bgpucap --list-metrics for the full list.
Env: BGPUCAP_METRICS.
macOS on Apple Silicon (M1/M2/M3/M4+), arm64 only. Reads AGX GPU metrics and unified memory statistics unavailable on Intel Macs or non-macOS platforms.
--color[=WHEN] — auto,
always, never, plain,
ansi, truecolor.
--color-scheme — default or
bright. Env: BGPUCAP_COLOR,
BGPUCAP_COLOR_SCHEME (GPUCAP_* still
accepted), plus NO_COLOR / CLICOLOR.
Core gpu, cpu, and memory
always work. Extended metrics (power, freq, thermal, …) are
best-effort on untested chips; omitted from output when unavailable.
Validated on Apple M4 Max; chip family in JSON
(chip.family: m1–m4).
Format vs. color:
When -f / --format (or
BGPUCAP_FORMAT; GPUCAP_FORMAT still accepted)
is set, output is always plain text — even with
--color=always. This matches BrightDate ecosystem
conventions: human reports colorize on TTY; machine format strings stay
script-safe.
Sample system metrics until Ctrl+C or --count N.
Default interval: 1000 ms (override with --interval).
bgpucap watch # live lines on stderr
bgpucap watch -n 10 --interval 500 # 10 samples every 500 ms
bgpucap watch -f json # NDJSON on stdout + summary JSON on exit
bgpucap watch --metrics basic --pid 1234
Diff two -f json captures. Compares the common subset of
metrics present in both files; one-sided metrics are skipped (noted on
stderr).
bgpucap -f json --metrics basic sleep 5 > before.json
# … run workload …
bgpucap -f json --metrics basic sleep 5 > after.json
bgpucap compare before.json after.json
gpuexercise drives sustained GPU load via a Metal compute
shader (subcommand, not a separate binary):
bgpucap gpuexercise --percent 50 --seconds 10
bgpucap gpuexercise -p 75 -s 5 -f json
bgpucap gpuexercise --mode sample -s 5 # ambient only
bgpucap gpuexercise --mode load -p 80 -s 5 # always generate load| Mode | Behavior |
|---|---|
best-effort (default) | Skip load if target ≤ ambient; suggests reachable --percent |
load | Always generate Metal load to chase target |
sample | No load; measure ambient GPU for the duration |
-f / --format
Custom format strings follow
BrightDate FORMAT-SPEC
where applicable, plus gpucap-specific utilization specifiers.
Set via -f or environment variable
BGPUCAP_FORMAT (GPUCAP_FORMAT still accepted).
bgpucap -f '%gA,%gP,%uA,%uP,%hA,%hP,%e,%Ws,%Wt' sleep 1
bgpucap -f json --metrics basic sleep 1 > report.json
bgpucap -f 'cmd=%C x=%x gpu_peak=%gP start=%Ws' cargo build
-f json:
Structured JSON on stdout (human reports on stderr).
Respects --metrics. Use with
bgpucap compare for before/after diffs.
All percentages output one decimal place, no % suffix.
| Specifier | Meaning |
|---|---|
| %gA / %gP | GPU average / peak % |
| %gI / %gJ | GPU memory in use (bytes) avg / peak |
| %gM / %gO | GPU memory allocated (bytes) avg / peak |
| %gR / %gS | Renderer utilization % avg / peak |
| %gL / %gY | Tiler utilization % avg / peak |
| %gF / %gV | GPU frequency MHz avg / peak |
| %gU / %gW | GPU temperature °C avg / peak |
| %gT | Thermal throttle (% of samples) |
| %uA / %uP | CPU average / peak % (system-wide) |
| %uF / %uV | CPU frequency MHz avg / peak (blended E/P) |
| %gB / %gK | GPU power (W) avg / peak |
| %gC / %gD | Command process GPU % avg / peak |
| %gN / %gQ | GPU SRAM power (W) avg / peak |
| %uE / %uQ | E-core CPU frequency MHz avg / peak |
| %uH / %uZ | P-core CPU frequency MHz avg / peak |
| %uB / %uK | CPU package power (W) avg / peak |
| %uG / %uR | E-core power (W) avg / peak |
| %uI / %uS | P-core power (W) avg / peak |
| %aB / %aK | ANE power (W) avg / peak |
| %hG / %hJ | DRAM power (W) avg / peak |
| %hA / %hP | Unified memory average / peak % |
| %hW / %hX | Wired memory bytes avg / peak |
| %hC / %hD | Compressed memory bytes avg / peak |
| %hS / %hO | Swap used bytes avg / peak |
| %hK / %hL | Memory pressure level avg / peak (0–2) |
| %tG | Exercise target GPU % (gpuexercise only) |
Shared with btime -f — see FORMAT-SPEC tiers A–C.
| Specifier | Meaning | Output |
|---|---|---|
| %Ws / %N | Command start wall time | {:.9} BrightDate days |
| %Wt / %n | Command end wall time | {:.9} BrightDate days |
| %e | Elapsed seconds | sec.centis (GNU style) |
| %E | Elapsed wall time | m:ss.cc or h:mm:ss |
| %B | Elapsed wall time | {:.9} BrightDate days |
| %b | Elapsed millidays | {:.6} (no suffix) |
| %dE | Elapsed millidays | {:.6} md |
| %C | Command line | argv joined with spaces |
| %x | Exit status | child exit code |
| %% | Literal % | |
| \t, \n | Tab / newline |
Default machine format:
%gA,%gP,%uA,%uP,%hA,%hP,%e,%Ws,%Wt\n
| Metric | Source | Notes |
|---|---|---|
| GPU % | IOKit Device Utilization % |
IOReport GPUPH fallback |
| GPU memory | IOKit PerformanceStatistics |
In use / allocated unified memory bytes |
| GPU frequency | IOReport + pmgr voltage-states9 |
Weighted MHz from P-state residency |
| GPU thermal | IOReport GPU_CLTM, Tg*a Max |
Throttle % and die temperature |
| GPU / CPU / DRAM power | IOReport Energy Model | GPU Energy (nJ), CPU Energy / DRAM (mJ) → watts |
| ANE power | IOReport Energy Model | ANE total or ANE0 shard counters |
| E-core / P-core power | IOReport Energy Model | EACC_CPU / ECPU, sum of PACC*_CPU |
| CPU | Mach host_processor_info |
System-wide; E/P MHz and blended freq from IOReport PCPU/ECPU |
| Memory | host_statistics64, vm.swapusage |
Unified RAM %, wired, compressed, swap, pressure |
Extended metrics are validated on Apple M4 Max. On other
Apple Silicon chips, bgpucap prints a footnote and reports best-effort values.
Samples are taken every --interval ms (default 100) while
the child runs. Average and peak are computed over all samples.
cargo install gpucap
bgpucap sleep 1brew tap digital-defiance/tap
brew install digital-defiance/tap/gpucap
bgpucap sleep 1
# Homebrew also symlinks gpucap → bgpucapbgpucap --version
bgpucap --help
man bgpucap
bgpucap -f '%gA,%uA,%e' sleep 0.1
man/bgpucap.1 ships with the crate. Homebrew installs it
as man bgpucap. Documents options, format specifiers,
environment variables, and the gpuexercise,
watch, and compare subcommands.
man bgpucap # after brew install
man bgpucap | grep -A2 FORMAT # format specifiers
Crate name remains gpucap; command is
bgpucap. Homebrew symlinks gpucap →
bgpucap.