Battery
Reports laptop battery charge level, wear health, cycle count, and status. Emitted only on hosts with at least one system battery (BAT*); servers and desktops report nothing.
Trait Path
battery
Fields
| Path | Type | Example | Description |
|---|---|---|---|
battery.health_pct |
number | 66.5 |
Worst battery's wear health (energy_full ÷ energy_full_design × 100). The value the server classifies onto the Agent Health card |
battery.ac_online |
boolean | false |
Whether an AC adapter is connected |
battery.batteries.<name>.manufacturer |
string | "LGC" |
Cell manufacturer (omitted when firmware doesn't report it) |
battery.batteries.<name>.model_name |
string | "DELL ABC1234" |
Battery model (omitted when absent) |
battery.batteries.<name>.serial_number |
string | "0001" |
Battery serial number (omitted when absent) |
battery.batteries.<name>.technology |
string | "Li-poly" |
Cell chemistry, e.g. Li-ion / Li-poly (omitted when absent) |
battery.batteries.<name>.capacity_pct |
integer | 73 |
Current charge level (0–100) |
battery.batteries.<name>.health_pct |
number | 66.5 |
This cell's wear health |
battery.batteries.<name>.status |
string | "Discharging" |
Charging / Discharging / Full / Not charging / Unknown |
battery.batteries.<name>.cycle_count |
integer | 412 |
Charge cycles (omitted when the battery doesn't report it) |
battery.batteries.<name>.energy_full_wh |
number | 35.9 |
Present full-charge capacity in watt-hours |
battery.batteries.<name>.energy_full_design_wh |
number | 54.0 |
Design capacity in watt-hours |
battery.batteries.<name>.voltage_now_v |
number | 12.27 |
Present terminal voltage, volts (omitted when firmware doesn't report it) |
battery.batteries.<name>.voltage_min_design_v |
number | 11.1 |
Firmware's voltage_min_design, volts — see the caution below (omitted when absent or zero) |
battery.batteries.<name>.power_now_w |
number | 5.0 |
Instantaneous load, watts. Read from power_now where available, otherwise synthesized as voltage_now × current_now |
battery.batteries.<name>.time_to_empty_secs |
integer | 6300 |
Estimated seconds until empty — present only while Discharging |
battery.batteries.<name>.time_to_full_secs |
integer | 2700 |
Estimated seconds until full — present only while Charging |
The batteries keys are sysfs names (e.g. BAT0, BAT1).
time_to_empty_secs / time_to_full_secs are instantaneous-rate estimates — they jitter with system load and are display-only (they do not feed the health classification).
Reading the delivery fields
voltage_now_v, voltage_min_design_v and power_now_w describe a pack's ability to deliver current, which is a different property from the wear health above and is not classified. Two cautions, both measured rather than assumed:
voltage_min_design_vis not a discharge floor. Firmware routinely populatesvoltage_min_designwith the pack's nominal voltage instead — on two laptops in the reference fleet it reads 11.25 V and 11.1 V across 3 cells, i.e. 3.7–3.75 V per cell, which is nominal rather than the ~3.0 V/cell empty cutoff. A healthy pack therefore sits below this figure for the bottom third of an ordinary discharge. Do not compute a "margin" from it and do not alert on one.- These are check-in-cadence samples. A pack that fails to deliver current sags for milliseconds and the machine is gone; a sample taken once per check-in cannot see that. The fields trend a pack over weeks and give a diagnosis something to work from after the fact — they are not an early-warning trigger, and Vigo deliberately ships no threshold on them.
Health Classification
On the per-envoy Agent Health card, battery.health_pct renders as a colored pill and rolls into the composite worst-signal score:
- warn below 80% of design capacity
- fail below 70%
A worn cell therefore raises the envoy's overall Agent Health severity, surfacing on the dashboard Agent Health card and the /agent-health page automatically.
Collection Method
Walks /sys/class/power_supply/. Each Battery-type entry named BAT* contributes a row; Mains-type entries supply ac_online. Identity fields (manufacturer, model_name, serial_number, technology) are read straight from the matching sysfs attributes and omitted when the firmware leaves them blank. Wear health uses energy_full ÷ energy_full_design (µWh), falling back to charge_full ÷ charge_full_design (µAh) — the ratio is unit-independent. Time-to-empty/full uses energy_now ÷ power_now (µWh ÷ µW), falling back to charge_now ÷ current_now (µAh ÷ µA); both divide to hours. Voltages come from voltage_now / voltage_min_design (µV). Load prefers power_now (µW); on packs that report only the charge family — which have no power_now node at all — it is synthesized from voltage_now × current_now, using the magnitude of current_now because drivers disagree on its sign while discharging. Pure sysfs reads; no subprocess, no upower dependency.
Using in Templates
- name: battery-report
type: file
target_path: /var/lib/vigo/battery.txt
content: |
{{ range $name, $bat := .Traits.battery.batteries }}{{ $name }}: {{ $bat.capacity_pct }}% charge, {{ $bat.health_pct }}% health ({{ $bat.status }})
{{ end }}
Platform
Linux