Repository Public License
1<!--2ORIX Monitor3File: docs/metrics/power.md4Author: Simon-Pierre Boucher5Contact: contact@spboucher.ai6-->78# Power metrics910Sources: `Collectors/PowerThermalGPU.swift` (`PowerCollector`, `PowerMath`, `PowerSample`, `PowerSourceKind`), `Collectors/ProcessCollector.swift` (per-process energy), `Metrics/Metric.swift`, `App/Sources/Features/SystemViews.swift` (`PowerView`).1112## Three sources, three levels of trust1314| Source | Interface | Trust | Gate |15|---|---|---|---|16| Power-source API | IOKit `IOPowerSources` (`IOPSCopyPowerSourcesInfo`, `IOPSGetProvidingPowerSourceType`, `IOPSGetPowerSourceDescription`, `IOPSCopyExternalPowerAdapterDetails`), `ProcessInfo.isLowPowerModeEnabled` | Documented | always read |17| Battery gauge registry entry | IORegistry service `AppleSmartBattery`, all properties via `IORegistryEntryCreateCFProperties` | **Best effort**: a public IOKit call on property names Apple does not document | only if `bestEffortMetrics` is on **and** the Mac has a battery |18| Kernel energy accounting | `rusage_info_v4.ri_billed_energy` via `proc_pid_rusage` | Documented structure; an accounting figure, own processes only | process tier |1920## Stored metrics2122Battery values are read on the **slow tier**: every 30 s by default, and immediately after a power-state change, a thermal-state change, a volume mount/unmount or a network-path change (`invalidateSlowReadings()`). The last reading is written to the store on every tick. Nothing is stored on a Mac without a battery.2324| Key (`MetricID`) | Name | Unit | Quality | Source | Stored value |25|---|---|---|---|---|---|26| `battery.charge` (`batteryCharge`) | Battery charge | percent | measured | IOKit `IOPowerSources` | `kIOPSCurrentCapacityKey / kIOPSMaxCapacityKey × 100` for the internal battery |27| `battery.power` (`batteryPower`) | Battery power flow | watts | bestEffort | IORegistry `AppleSmartBattery` (`Voltage`, `Amperage`) | `voltage (V) × amperage (A)`; **negative while discharging**, positive while charging |28| `battery.temperature` (`batteryTemperature`) | Battery temperature | °C | bestEffort | IORegistry `AppleSmartBattery` (`Temperature`) | `value / 100`; see [thermal](thermal.md) |2930**Percentage convention:** `battery.charge` is 0–100 % of the battery's *current full-charge capacity* as published by the power-source API (the same figure as the menu bar battery indicator), not of its design capacity.3132## Battery flow is not system power3334`battery.power` is the power crossing the battery terminals.3536| Situation | Battery flow | Mac's actual consumption |37|---|---|---|38| On battery | Negative; its magnitude approximates what the Mac draws | ≈ −flow |39| On adapter, charging | Positive (energy going into the battery) | Supplied by the adapter; **not** given by this figure |40| On adapter, full | Near zero | Supplied by the adapter; **not** given by this figure |4142The catalogue method and the Power page both say it: "This is the battery flow, not the power drawn by the whole Mac on AC."4344## Registry parsing — `PowerMath.batteryFields(registry:)`4546The parser accepts two layouts and treats every field as optional.4748| Field | Keys tried, in order | Conversion | Validation |49|---|---|---|---|50| `cycles` | `CycleCount` | — | — |51| `design` | `DesignCapacity`, then `BatteryData.DesignCapacity` | mAh | must be > 0 |52| `maximum` | `AppleRawMaxCapacity`, `NominalChargeCapacity`, `BatteryData.NominalChargeCapacity`, `BatteryData.FullChargeCapacity` | mAh | must be > 0 |53| `volts` | `Voltage` | mV → V (÷ 1000) | — |54| `amps` | `Amperage` | mA → A (÷ 1000), signed | — |55| `celsius` | `Temperature`, then `BatteryData.Temperature` | ÷ 100 | must be within −40…150 and non-zero |56| `systemWatts` | `PowerTelemetryData.SystemLoad` | mW → W (÷ 1000) | must be > 0 |5758Two facts verified on the audited Mac (macOS 27.0):5960- The registry entry **nests capacities under `BatteryData`**, publishes **no `Temperature` key**, and has a **`PowerTelemetryData.SystemLoad`** value. The unit test `nestedBatteryLayout` reproduces that shape; `flatBatteryLayoutAndImplausibleTemperature` covers the older flat layout.61- **Registry integers are unsigned 64-bit even for signed quantities.** A discharge current of −2005 mA is published as 2⁶⁴ − 2005. `PowerMath.signed(_:)` reinterprets the bit pattern (`Int64(truncatingIfNeeded:)`); without it the battery flow would be an absurd positive number.6263Derived in `PowerSample`:6465```66batteryWatts = voltage × amperage (nil unless both are present)67capacityRatio = maxCapacity / designCapacity (nil unless both are present, 0…1 nominally)68```6970## Displayed values7172Power page (`PowerView`), on a Mac with a battery:7374| Card | Value | Source | Badge | Stored |75|---|---|---|---|---|76| Battery | Charge, state (Fully charged / Charging / On AC power, not charging / On battery / On UPS power) | IOPowerSources | — | charge |77| | Power source (AC adapter, Battery, UPS) | `IOPSGetProvidingPowerSourceType` | — | no |78| | Time remaining / Time until full | `kIOPSTimeToEmptyKey` / `kIOPSTimeToFullChargeKey` (minutes, only when > 0) | **Estimate** | no |79| | Low Power Mode | `ProcessInfo.isLowPowerModeEnabled` | — | no |80| | Adapter wattage and name | `IOPSCopyExternalPowerAdapterDetails` (`kIOPSPowerAdapterWattsKey`, `Name`) | — | no |81| Charge | Live chart of `battery.charge`, 0–100 % | — | — | yes |82| Health | Condition reported by macOS (`kIOPSBatteryHealthKey`: Good / Fair / Poor …) | IOPowerSources | card badge | no |83| | Cycle count, full-charge capacity (mAh), design capacity (mAh), capacity relative to design | AppleSmartBattery | **Best effort** | no |84| Power flow | Battery flow (W), voltage (V), current (A) | AppleSmartBattery | **Best effort** | flow |85| | System load (battery gauge) (W) | `PowerTelemetryData.SystemLoad` | **Best effort** | no |86| Energy by process | Up to eight of the user's processes with the highest billed power (W), above 0.01 W | `ri_billed_energy` | — | no |8788On a Mac without a battery the page shows the power source, Low Power Mode, and an unavailable row: "Desktop Macs expose no power figure through supported system interfaces."8990While the system has no estimate and the battery is not full, the time row reads "Calculating…".9192The Health card adds: "System Settings › Battery remains the reference for battery health."9394### Time remaining9596The values are **the system's estimate**, passed through. ORIX Monitor does not compute its own projection from the flow, and labels the row "Estimate". The capability resolver classifies `power.timeremaining` as `estimated`.9798### System load (battery gauge)99100`PowerSample.systemWatts` is described in code as "Power drawn by the whole Mac in watts, from the battery gauge's telemetry block. Best effort." It exists only on portable Macs, is displayed with a "Best effort" badge, and is **not stored** as a metric, so it has no history, no alert and no place in reports.101102### Per-process power103104```105power (W) = (ri_billed_energy₁ − ri_billed_energy₀) / 10⁹ / elapsedSeconds106```107108`ri_billed_energy` is in nanojoules. The result is the **average** power the kernel billed to the process over the last process-sampling interval (4 s by default). It is `nil` on a process's first sample and for processes of other users. The page describes it as "an accounting figure, useful to compare processes, not a measurement at the wall", and the Processes inspector labels it "Power (kernel accounting)".109110## Effect on sampling111112The power reading also drives the scheduler: with the battery saver on (default), the effective sampling interval doubles when `PowerSample.source == .battery` or `lowPowerMode` is true. See [telemetry](../architecture/telemetry.md).113114## Quality classes115116- `measured` — battery charge.117- `estimated` — time remaining and time until full (not stored).118- `bestEffort` — battery flow, voltage, current, cycle count, capacities, battery temperature, system load.119120## Limitations121122- **Slow tier.** Battery values change at most every 30 s in the store (sooner on a power-source change). The power-flow chart is therefore a step series at that cadence.123- **Best-effort keys can vanish.** If a key is renamed, the corresponding row shows "—". Nothing is substituted.124- **Capacity ratio is not Apple's "Maximum Capacity".** It is full-charge capacity divided by design capacity from raw gauge values; System Settings applies its own processing. ORIX Monitor points to System Settings as the reference.125- **Which "maximum" key is found first varies by system**, so the full-charge figure may come from `AppleRawMaxCapacity` on one Mac and `NominalChargeCapacity` on another.126- **Only the internal battery is read.** A UPS is recognised as the providing source, but its charge is not reported; other power sources are ignored.127- **Per-process energy covers the user's own processes only** and reflects the kernel's billing model, not a physical measurement.128- **Verified on one portable Mac.** Behaviour on a desktop Mac follows from the code paths (`hasBattery == false`) but was not observed.129130## Deliberately not shown131132| Item | Reason |133|---|---|134| Total system power on a desktop Mac | No supported interface exposes it. Shown as unavailable. |135| CPU / GPU / package power, per-cluster power | Available only from `powermetrics`, which requires root. ORIX Monitor runs without administrator rights and spawns no tool. |136| Adapter voltage and current, charging wattage negotiated | Not read; only the adapter's rated wattage and name from the documented API. |137| An app-computed time-remaining estimate | The system's estimate is shown instead, labelled as an estimate. |138| A battery "health percentage" presented as authoritative | The raw capacity ratio is shown under its own name with a "Best effort" badge. |139| Battery serial number, manufacture date | Not read. |140| Energy impact scores as in Activity Monitor | Activity Monitor's "Energy Impact" is a composite Apple does not specify; ORIX Monitor shows billed watts instead. |141