SPB Git

Repository Public License

power.md 9.9 KB

# 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 no Temperature key, and has a PowerTelemetryData.SystemLoad value. The unit test nestedBatteryLayout reproduces that shape; flatBatteryLayoutAndImplausibleTemperature covers 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:

text
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

text
power (W) = (ri_billed_energy₁ − ri_billed_energy₀) / 10⁹ / elapsedSeconds

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)".

# 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 AppleRawMaxCapacity on one Mac and NominalChargeCapacity on 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.
Files main
Menu

Theme