Power metrics
Sources: Collectors/PowerThermalGPU.swift (PowerCollector, PowerMath, PowerSample, PowerSourceKind), Collectors/ProcessCollector.swift (per-process energy), Metrics/Metric.swift, App/Sources/Features/SystemViews.swift (PowerView).
Three sources, three levels of trust
| Source | Interface | Trust | Gate |
|---|---|---|---|
| Power-source API | IOKit IOPowerSources (IOPSCopyPowerSourcesInfo, IOPSGetProvidingPowerSourceType, IOPSGetPowerSourceDescription, IOPSCopyExternalPowerAdapterDetails), ProcessInfo.isLowPowerModeEnabled |
Documented | always read |
| 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 |
| Kernel energy accounting | rusage_info_v4.ri_billed_energy via proc_pid_rusage |
Documented structure; an accounting figure, own processes only | process tier |
Stored metrics
Battery 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.
Key (MetricID) |
Name | Unit | Quality | Source | Stored value |
|---|---|---|---|---|---|
battery.charge (batteryCharge) |
Battery charge | percent | measured | IOKit IOPowerSources |
kIOPSCurrentCapacityKey / kIOPSMaxCapacityKey × 100 for the internal battery |
battery.power (batteryPower) |
Battery power flow | watts | bestEffort | IORegistry AppleSmartBattery (Voltage, Amperage) |
voltage (V) × amperage (A); negative while discharging, positive while charging |
battery.temperature (batteryTemperature) |
Battery temperature | °C | bestEffort | IORegistry AppleSmartBattery (Temperature) |
value / 100; see thermal |
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.
Battery flow is not system power
battery.power is the power crossing the battery terminals.
| Situation | Battery flow | Mac's actual consumption |
|---|---|---|
| On battery | Negative; its magnitude approximates what the Mac draws | ≈ −flow |
| On adapter, charging | Positive (energy going into the battery) | Supplied by the adapter; not given by this figure |
| On adapter, full | Near zero | Supplied by the adapter; not given by this figure |
The catalogue method and the Power page both say it: "This is the battery flow, not the power drawn by the whole Mac on AC."
Registry parsing — PowerMath.batteryFields(registry:)
The parser accepts two layouts and treats every field as optional.
| Field | Keys tried, in order | Conversion | Validation |
|---|---|---|---|
cycles |
CycleCount |
— | — |
design |
DesignCapacity, then BatteryData.DesignCapacity |
mAh | must be > 0 |
maximum |
AppleRawMaxCapacity, NominalChargeCapacity, BatteryData.NominalChargeCapacity, BatteryData.FullChargeCapacity |
mAh | must be > 0 |
volts |
Voltage |
mV → V (÷ 1000) | — |
amps |
Amperage |
mA → A (÷ 1000), signed | — |
celsius |
Temperature, then BatteryData.Temperature |
÷ 100 | must be within −40…150 and non-zero |
systemWatts |
PowerTelemetryData.SystemLoad |
mW → W (÷ 1000) | must be > 0 |
Two facts verified on the audited Mac (macOS 27.0):
- The registry entry nests capacities under
BatteryData, publishes noTemperaturekey, and has aPowerTelemetryData.SystemLoadvalue. The unit testnestedBatteryLayoutreproduces that shape;flatBatteryLayoutAndImplausibleTemperaturecovers the older flat layout. - 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.
Derived in PowerSample:
batteryWatts = voltage × amperage (nil unless both are present)
capacityRatio = maxCapacity / designCapacity (nil unless both are present, 0…1 nominally)Displayed values
Power page (PowerView), on a Mac with a battery:
| Card | Value | Source | Badge | Stored |
|---|---|---|---|---|
| Battery | Charge, state (Fully charged / Charging / On AC power, not charging / On battery / On UPS power) | IOPowerSources | — | charge |
| Power source (AC adapter, Battery, UPS) | IOPSGetProvidingPowerSourceType |
— | no | |
| Time remaining / Time until full | kIOPSTimeToEmptyKey / kIOPSTimeToFullChargeKey (minutes, only when > 0) |
Estimate | no | |
| Low Power Mode | ProcessInfo.isLowPowerModeEnabled |
— | no | |
| Adapter wattage and name | IOPSCopyExternalPowerAdapterDetails (kIOPSPowerAdapterWattsKey, Name) |
— | no | |
| Charge | Live chart of battery.charge, 0–100 % |
— | — | yes |
| Health | Condition reported by macOS (kIOPSBatteryHealthKey: Good / Fair / Poor …) |
IOPowerSources | card badge | no |
| Cycle count, full-charge capacity (mAh), design capacity (mAh), capacity relative to design | AppleSmartBattery | Best effort | no | |
| Power flow | Battery flow (W), voltage (V), current (A) | AppleSmartBattery | Best effort | flow |
| System load (battery gauge) (W) | PowerTelemetryData.SystemLoad |
Best effort | no | |
| 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 |
On 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."
While the system has no estimate and the battery is not full, the time row reads "Calculating…".
The Health card adds: "System Settings › Battery remains the reference for battery health."
Time remaining
The 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.
System load (battery gauge)
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.
Per-process power
power (W) = (ri_billed_energy₁ − ri_billed_energy₀) / 10⁹ / elapsedSecondsri_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)".
Effect on sampling
The 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.
Quality classes
measured— battery charge.estimated— time remaining and time until full (not stored).bestEffort— battery flow, voltage, current, cycle count, capacities, battery temperature, system load.
Limitations
- 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.
- Best-effort keys can vanish. If a key is renamed, the corresponding row shows "—". Nothing is substituted.
- 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.
- Which "maximum" key is found first varies by system, so the full-charge figure may come from
AppleRawMaxCapacityon one Mac andNominalChargeCapacityon another. - 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.
- Per-process energy covers the user's own processes only and reflects the kernel's billing model, not a physical measurement.
- Verified on one portable Mac. Behaviour on a desktop Mac follows from the code paths (
hasBattery == false) but was not observed.
Deliberately not shown
| Item | Reason |
|---|---|
| Total system power on a desktop Mac | No supported interface exposes it. Shown as unavailable. |
| CPU / GPU / package power, per-cluster power | Available only from powermetrics, which requires root. ORIX Monitor runs without administrator rights and spawns no tool. |
| Adapter voltage and current, charging wattage negotiated | Not read; only the adapter's rated wattage and name from the documented API. |
| An app-computed time-remaining estimate | The system's estimate is shown instead, labelled as an estimate. |
| A battery "health percentage" presented as authoritative | The raw capacity ratio is shown under its own name with a "Best effort" badge. |
| Battery serial number, manufacture date | Not read. |
| 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. |