Fill the macOS GPU monitoring gap in internal/perf/monitor_darwin.go using ioreg for Apple Silicon

[Pauliehedron]

Title

Fill the macOS GPU monitoring gap in internal/perf/monitor_darwin.go using ioreg for Apple Silicon

Category

Ideas

One-paragraph summary

internal/perf/ monitors CPU, memory, swap, and load on all platforms, and GPU on Linux (LACT → nvidia-smi → rocm-smi) and Windows (nvidia-smi). On macOS (monitor_darwin.go), the GPU path is return nil, ErrNotImplemented — a hardcoded stub. Apple Silicon Macs are a significant deployment target for llama.cpp and llama-swap (unified memory is well-suited for local models), and the data is available from the IOKit driver via ioreg -c IOGPU -d 1, which returns GPU utilization percentages and memory allocation in a simple text dictionary.

Data available from Apple Silicon

Existing GpuStat field	Source
GpuUtilPct	ioreg → PerformanceStatistics → "Device Utilization %" (0-100)
MemUsedMB, MemTotalMB	Same dict — "In use system memory" / "Alloc system memory" (bytes, /1M)
ID, Name	From IONameMatched key in ioreg output (e.g., gpu,t6000) or system_profiler SPDisplaysDataType

Three fields Apple Silicon cannot supply remain at Go zero-values (which Prometheus output already handles gracefully by omitting zero metrics): TempC, FanSpeedPct, PowerDrawW — no public macOS API exposes these. Unified memory means MemTotalMB is GPU-allocated portion, not discrete VRAM.

Shape of the change

One function in one file: replace the stub getGpuStats() in internal/perf/monitor_darwin.go with an implementation that:

1. Probes ioreg -c IOGPU — if it returns data (Apple Silicon), proceed. If empty or not found (Intel Mac, AMD), return ErrNoGpuTool preserving current behavior.
2. Runs ioreg -r -c IOGPU -d 1 at the configured interval via exec.CommandContext, same exec/pipe/scanner pattern already used for nvidia-smi on Linux/Windows.
3. Parses the PerformanceStatistics dictionary — key-value text with quoted keys, unquoted integer values. Trivially parseable with Go's bufio.Scanner and strings package, same pattern as gpu_parse.go.
4. Publishes GpuStat snapshots on the existing channel.

No new config keys, no build-tag changes, no new dependencies. The //go:build darwin tag already isolates this file. No platform-version detection needed — ioreg -c IOGPU returns data on Apple Silicon regardless of macOS version, and returns nothing on Intel.

Why it matters

Apple Silicon is the primary hardware for local LLM inference on macOS. Users running llama-swap on their Macs currently get zero GPU visibility in /metrics — they see CPU per-core, memory, swap, and load averages but a blank GPU section in the web UI. The data is already in the kernel's IOKit tree; the project just needs to ask for it.

Implementation flexibility

The parsing is the only variable part. The PerformanceStatistics dict is text-based and stable across macOS releases (Apple has not changed these IOKit keys in years). It could be parsed with:

• bufio.Scanner + strings.Split/Trim — matches existing nvidia-smi pattern
• Regex — same reliability, slightly more concise
• A simple key-value loop scanning for "Key" = Value lines

All three are zero-dependency. The data rate (one poll per 5s by default) is negligible — ioreg completes in ~100ms.

---

Idea drafted with assistance from Ensemble (ENSEMBLE Framework v3.3.3 protocol on Hermes Agent). Accountable human: @Pauliehedron, Conductor

[mostlygeek]

Trying out ioreg -c IOGPU -d 1 gives no information on an M4 Max. Ideally any solution for darwin would not require root permissions to access the information. My early searches all the solutions required using sudo or root level permissions.

[Pauliehedron]

Studio M1 Max here (Mac13.1, macOS 26.5). Verified with: ioreg -r -c IOGPU -d 1 from a regular user session — no sudo required.

paulie@Mac-Studio ~ % ioreg -r -c IOGPU -d 1 f
+-o AGXAcceleratorG13X <class AGXAcceleratorG13X, id 0x100000aa3, registered, matched, active, busy 0 (5608 ms), retain 86>
{
"SchedulerState" = {"Stamps"=(),"BusyWorkQueues"=()}
"IOMatchedAtBoot" = Yes
"vendor-id" = <6b100000>
"GPURawCounterBundleName" = "AGXGPURawCounterBundle"
"MetalStatisticsName" = "AGXMetalStatisticsExternalA14X"
"AGXParameterBufferMaxSizeEverMemless" = 18446744071714111488
"GPURawCounterPluginClassName" = "AGXGPURawCounterSourceGroup"
"MetalPluginClassName" = "AGXG13XDevice"
"SCMVersionNumber" = ""
"AGCInfo" = {"fLastSubmissionPID"=60472,"fSubmissionsSinceLastCheck"=0,"fBusyCount"=0}
"MetalPluginName" = "AGXMetalG13X"
"IONameMatched" = "gpu,t6000"
"CommandSubmissionEnabled" = Yes
"PerformanceStatistics" = {"In use system memory (driver)"=0,"Alloc system memory"=35691986944,"Tiler Utilization %"=23,"recoveryCount"=0,"lastRecoveryTime"=0,"Renderer Utilization %"=22,"TiledSceneByte$
"IOGLBundleName" = "AppleMetalOpenGLRenderer"
"AGXParameterBufferMaxSizeNeverMemless" = 1149763584
"IOGLESBundleName" = "AppleMetalGLRenderer"
"IOSourceVersion" = "351.2"
"IOPersonalityPublisher" = "com.apple.AGXG13X"
"IOPowerManagement" = {"CurrentPowerState"=1,"CapabilityFlags"=2,"MaxPowerState"=1,"DriverPowerState"=1}
"model" = "Apple M1 Max"
"AGXTraceCodeVersion" = "3.44.6"
"SCMBuildTime" = ""
"CFBundleIdentifier" = "com.apple.AGXG13X"
"gpu-core-count" = 32
"IOProviderClass" = "AppleARMIODevice"
"AGXParameterBufferMaxSize" = 18446744072863875072
"IONameMatch" = ("gpu,t8015","gpu,t8027","gpu,t8030","gpu,t8103","gpu,t6000","gpu,t6001","gpu,t6002")
"IOReportLegendPublic" = Yes
"IOClass" = "AGXAcceleratorG13X"
"CFBundleIdentifierKernel" = "com.apple.AGXG13X"
"GPUConfigurationVariable" = {"num_gps"=16,"gpu_gen"=13,"is_sksm"=0,"usc_gen"=2,"num_cores"=32,"num_mgpus"=4,"gpu_var"="C","core_mask_list"=(255,255,255,255),"num_frags"=32}
"IOGeneralInterest" = "IOCommand is not serializable"
"IOReportLegend" = ({"IOReportChannels"=((1,6442450945,"Alloc system memory"),(2,6442450945,"In use system memory"),(3,6442450945,"GPU Restart Count"),(4,6442450945,"In use system memory (driver)"),(5,6$
"IOMatchCategory" = "IOAccelerator"
"IOProbeScore" = 10000
"KDebugVersion" = 4294967296
"SurfaceList" = ()
}

[mostlygeek]

See PR #816

Using a combo of mactop and ioreg (I got it to work) we can get performance stats for OSX. mactop is easy to install with brew install mactop and if llama-swap should be able to find it and use it to show performance metrics.

[Pauliehedron]

I already run mactop as well, it's been my standard living in llama-server --models-max=1 world until I found llama-swap and can run 3 models without OOM crashing.

[mostlygeek]

Awesome. Please let me know how the new darwin support goes. :)