SPB Git

Repository Public License

gpu.md 7.0 KB

# GPU metrics

Sources: Collectors/PowerThermalGPU.swift (GPUCollector, GPUDevice, GPUStatistics), Metrics/Metric.swift, App/Sources/Features/ComputeViews.swift (GPUView).

# Summary

macOS has no supported API for system-wide GPU utilization. ORIX Monitor separates what is documented from what is not:

Information Interface Status
Which GPUs exist and what they can do Metal (MTLCopyAllDevices) Documented, public
How busy the GPU is IORegistry IOAccelerator → PerformanceStatistics Public IOKit call, undocumented property names → "Best effort"

Everything in the second row is labelled "Best effort" wherever it appears, and can be switched off as a whole.

# Stored metric

Key (MetricID) Name Unit Quality Source Stored value
gpu.utilization (gpuUtilization) GPU utilization percent bestEffort IORegistry IOAccelerator "PerformanceStatistics" "Device Utilization %" as published by the graphics driver, clamped to 0…100. With several accelerators, the maximum over devices
  • Percentage convention: 0–100 % of the device, as defined by the driver. ORIX Monitor does not rescale, smooth or otherwise adjust it.
  • Refresh: every tick of the fast tier (2 s by default while a window is visible; see telemetry), only while TelemetryConfiguration.bestEffortMetrics is on.
  • Absent when: best-effort readings are off, no IOAccelerator service publishes a PerformanceStatistics dictionary, or the dictionary lacks the key. In those cases nothing is stored for that tick; no zero is written.

# How it is read

GPUCollector.statistics():

  1. IOServiceGetMatchingServices(kIOMainPortDefault, IOServiceMatching("IOAccelerator"), …).
  2. For each service, IORegistryEntryCreateCFProperties → a dictionary.
  3. GPUCollector.parse(registry:) requires the PerformanceStatistics sub-dictionary and returns nil without it.

Fields of GPUStatistics:

Field Registry key Unit Processing
name model, else IOClass, else "GPU" — —
coreCount gpu-core-count count —
deviceUtilization PerformanceStatistics["Device Utilization %"] percent clamped 0…100
rendererUtilization PerformanceStatistics["Renderer Utilization %"] percent clamped 0…100
tilerUtilization PerformanceStatistics["Tiler Utilization %"] percent clamped 0…100
memoryInUse PerformanceStatistics["In use system memory"] bytes —
memoryAllocated PerformanceStatistics["Alloc system memory"] bytes —

The unit test gpuStatisticsParsing covers the clamp, a missing key (→ nil) and a registry without PerformanceStatistics (→ no statistics).

No rate is computed: these are instantaneous values published by the driver, so the GPU collector keeps no baseline and needs no reset after sleep.

# Displayed values

GPU page (GPUView):

Card Content Badge
Utilization Device utilization (large readout), renderer, tiler, GPU cores Best effort
Utilization history Live chart of gpu.utilization over the in-memory window, fixed 0–100 % scale Best effort
About this figure A paragraph explaining the source, that the figure is "shown as published, never adjusted", that it can disappear with a system update, and where to turn it off —
Memory "In use by the GPU", "Allocated by the driver"; a note when the GPU shares unified memory Best effort
Not available Per-process GPU usage, GPU temperature, GPU power draw Unavailable
One card per Metal device Unified memory, recommended working set, largest buffer, ray tracing, low-power, removable (eGPU), headless, threads per threadgroup none (documented)

Elsewhere: the "GPU" dashboard widget, the sidebar badge, the History page (stored series), and the System Overview report.

# Fallback states

Situation What the page shows
Best-effort readings turned off "Best-effort readings are turned off in Settings."
The driver publishes no utilization "The graphics driver on this Mac publishes no utilization figure."

# Metal device properties

GPUCollector.devices() maps each MTLDevice to a GPUDevice. These are read once at launch.

Property Metal API Note
Name name —
Unified memory hasUnifiedMemory True on Apple Silicon
Recommended working set recommendedMaxWorkingSetSize Metal's suggested ceiling for this app's GPU allocations. It is not the amount of video memory installed, and the UI labels it "Recommended working set (Metal)"
Largest buffer maxBufferLength —
Ray tracing supportsRaytracing —
Low-power device isLowPower —
Removable (eGPU) isRemovable —
Headless isHeadless —
Threads per threadgroup maxThreadsPerThreadgroup.width —

supports32BitMSAA is collected but not displayed.

# Memory terms

On Apple Silicon the GPU has no dedicated video memory: it allocates from the same unified memory as the CPU. Consequently:

  • There is no "VRAM total / VRAM used" to report, and the page says so.
  • "In use by the GPU" and "Allocated by the driver" are driver counters of system memory held for graphics. They overlap with the figures on the memory page (they are not additional memory) and are best-effort values.

# Quality class

bestEffort for everything from PerformanceStatistics; the Metal properties are documented and carry no badge. The catalogue test catalogueDescribesEveryStoredMetric asserts that gpu.utilization is classified bestEffort.

# Limitations

  • The definition of "Device Utilization %" belongs to the driver and is not published. ORIX Monitor reports it; it cannot say exactly what the percentage measures.
  • The property names can change with any macOS or driver update; the figure would then disappear (it would not become wrong).
  • Multi-GPU aggregation is a maximum. The stored series does not distinguish devices. The page's detail rows show only the first accelerator returned.
  • Sampled, not averaged. A short burst between two samples is invisible; a sample taken during a burst overstates the interval.
  • Verified on one Mac (Apple M5 Max, macOS 27.0).

# Deliberately not shown

Item Reason
Per-process GPU usage No supported interface. Shown as unavailable.
GPU temperature SMC / private sensors only. See thermal.
GPU power draw Requires powermetrics (root). Shown as unavailable.
GPU frequency or power state Not exposed.
"VRAM" totals Meaningless with unified memory; Metal's working-set recommendation is shown under its own name instead.
A smoothed or "corrected" utilization The figure is passed through unchanged so that it can be compared with what the driver publishes.
Files main
Menu

Theme