Repository Public License
1<!--2ORIX Monitor3File: docs/metrics/gpu.md4Author: Simon-Pierre Boucher5Contact: contact@spboucher.ai6-->78# GPU metrics910Sources: `Collectors/PowerThermalGPU.swift` (`GPUCollector`, `GPUDevice`, `GPUStatistics`), `Metrics/Metric.swift`, `App/Sources/Features/ComputeViews.swift` (`GPUView`).1112## Summary1314macOS has **no supported API for system-wide GPU utilization**. ORIX Monitor separates what is documented from what is not:1516| Information | Interface | Status |17|---|---|---|18| Which GPUs exist and what they can do | Metal (`MTLCopyAllDevices`) | Documented, public |19| How busy the GPU is | IORegistry `IOAccelerator` → `PerformanceStatistics` | Public IOKit call, **undocumented property names** → "Best effort" |2021Everything in the second row is labelled "Best effort" wherever it appears, and can be switched off as a whole.2223## Stored metric2425| Key (`MetricID`) | Name | Unit | Quality | Source | Stored value |26|---|---|---|---|---|---|27| `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 |2829- **Percentage convention:** 0–100 % of the device, as defined by the driver. ORIX Monitor does not rescale, smooth or otherwise adjust it.30- **Refresh:** every tick of the fast tier (2 s by default while a window is visible; see [telemetry](../architecture/telemetry.md)), **only while `TelemetryConfiguration.bestEffortMetrics` is on**.31- **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.3233## How it is read3435`GPUCollector.statistics()`:36371. `IOServiceGetMatchingServices(kIOMainPortDefault, IOServiceMatching("IOAccelerator"), …)`.382. For each service, `IORegistryEntryCreateCFProperties` → a dictionary.393. `GPUCollector.parse(registry:)` requires the `PerformanceStatistics` sub-dictionary and returns `nil` without it.4041Fields of `GPUStatistics`:4243| Field | Registry key | Unit | Processing |44|---|---|---|---|45| `name` | `model`, else `IOClass`, else "GPU" | — | — |46| `coreCount` | `gpu-core-count` | count | — |47| `deviceUtilization` | `PerformanceStatistics["Device Utilization %"]` | percent | clamped 0…100 |48| `rendererUtilization` | `PerformanceStatistics["Renderer Utilization %"]` | percent | clamped 0…100 |49| `tilerUtilization` | `PerformanceStatistics["Tiler Utilization %"]` | percent | clamped 0…100 |50| `memoryInUse` | `PerformanceStatistics["In use system memory"]` | bytes | — |51| `memoryAllocated` | `PerformanceStatistics["Alloc system memory"]` | bytes | — |5253The unit test `gpuStatisticsParsing` covers the clamp, a missing key (→ `nil`) and a registry without `PerformanceStatistics` (→ no statistics).5455No rate is computed: these are instantaneous values published by the driver, so the GPU collector keeps no baseline and needs no reset after sleep.5657## Displayed values5859GPU page (`GPUView`):6061| Card | Content | Badge |62|---|---|---|63| Utilization | Device utilization (large readout), renderer, tiler, GPU cores | Best effort |64| Utilization history | Live chart of `gpu.utilization` over the in-memory window, fixed 0–100 % scale | Best effort |65| 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 | — |66| Memory | "In use by the GPU", "Allocated by the driver"; a note when the GPU shares unified memory | Best effort |67| Not available | Per-process GPU usage, GPU temperature, GPU power draw | Unavailable |68| One card per Metal device | Unified memory, recommended working set, largest buffer, ray tracing, low-power, removable (eGPU), headless, threads per threadgroup | none (documented) |6970Elsewhere: the "GPU" dashboard widget, the sidebar badge, the History page (stored series), and the System Overview report.7172### Fallback states7374| Situation | What the page shows |75|---|---|76| Best-effort readings turned off | "Best-effort readings are turned off in Settings." |77| The driver publishes no utilization | "The graphics driver on this Mac publishes no utilization figure." |7879## Metal device properties8081`GPUCollector.devices()` maps each `MTLDevice` to a `GPUDevice`. These are read once at launch.8283| Property | Metal API | Note |84|---|---|---|85| Name | `name` | — |86| Unified memory | `hasUnifiedMemory` | True on Apple Silicon |87| 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)" |88| Largest buffer | `maxBufferLength` | — |89| Ray tracing | `supportsRaytracing` | — |90| Low-power device | `isLowPower` | — |91| Removable (eGPU) | `isRemovable` | — |92| Headless | `isHeadless` | — |93| Threads per threadgroup | `maxThreadsPerThreadgroup.width` | — |9495`supports32BitMSAA` is collected but not displayed.9697## Memory terms9899On Apple Silicon the GPU has no dedicated video memory: it allocates from the same unified memory as the CPU. Consequently:100101- There is no "VRAM total / VRAM used" to report, and the page says so.102- "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](memory.md) page (they are not additional memory) and are best-effort values.103104## Quality class105106`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`.107108## Limitations109110- **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.111- **The property names can change** with any macOS or driver update; the figure would then disappear (it would not become wrong).112- **Multi-GPU aggregation is a maximum.** The stored series does not distinguish devices. The page's detail rows show only the first accelerator returned.113- **Sampled, not averaged.** A short burst between two samples is invisible; a sample taken during a burst overstates the interval.114- **Verified on one Mac** (Apple M5 Max, macOS 27.0).115116## Deliberately not shown117118| Item | Reason |119|---|---|120| Per-process GPU usage | No supported interface. Shown as unavailable. |121| GPU temperature | SMC / private sensors only. See [thermal](thermal.md). |122| GPU power draw | Requires `powermetrics` (root). Shown as unavailable. |123| GPU frequency or power state | Not exposed. |124| "VRAM" totals | Meaningless with unified memory; Metal's working-set recommendation is shown under its own name instead. |125| A smoothed or "corrected" utilization | The figure is passed through unchanged so that it can be compared with what the driver publishes. |126