battery.md

Semantic conventions for battery metrics

Status: Development

• Battery metrics hw.battery.*
  • Metric: hw.battery.charge
  • Metric: hw.battery.charge.limit
  • Metric: hw.battery.time_left
  • Metric: hw.status (Battery)

Battery metrics hw.battery.*

A battery in a computer system or an UPS.

hw.type MUST be set to "battery".

All battery metrics may include the below attributes to describe the characteristics of the monitored battery:

Attributes:

Key	Stability	Requirement Level	Value Type	Description	Example Values
hw.id		Required	string	An identifier for the hardware component, unique within the monitored host	win32battery_battery_testsysa33_1
hw.battery.capacity		Recommended	string	Design capacity in Watts-hours or Ampere-hours	9.3Ah; 50Wh
hw.battery.chemistry		Recommended	string	Battery chemistry, e.g. Lithium-Ion, Nickel-Cadmium, etc.	Li-ion; NiMH
hw.model		Recommended	string	Descriptive model name of the hardware component	PERC H740P; Intel(R) Core(TM) i7-10700K; Dell XPS 15 Battery
hw.name		Recommended	string	An easily-recognizable name for the hardware component	eth0
hw.parent		Recommended	string	Unique identifier of the parent component (typically the hw.id attribute of the enclosure, or disk controller)	dellStorage_perc_0
hw.vendor		Recommended	string	Vendor name of the hardware component	Dell; HP; Intel; AMD; LSI; Lenovo

Metric: hw.battery.charge

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
hw.battery.charge	Gauge	1	Remaining fraction of battery charge.

Attributes:

Key	Stability	Requirement Level	Value Type	Description	Example Values
hw.id		Required	string	An identifier for the hardware component, unique within the monitored host	win32battery_battery_testsysa33_1
hw.battery.capacity		Recommended	string	Design capacity in Watts-hours or Ampere-hours	9.3Ah; 50Wh
hw.battery.chemistry		Recommended	string	Battery chemistry, e.g. Lithium-Ion, Nickel-Cadmium, etc.	Li-ion; NiMH
hw.model		Recommended	string	Descriptive model name of the hardware component	PERC H740P; Intel(R) Core(TM) i7-10700K; Dell XPS 15 Battery
hw.name		Recommended	string	An easily-recognizable name for the hardware component	eth0
hw.parent		Recommended	string	Unique identifier of the parent component (typically the hw.id attribute of the enclosure, or disk controller)	dellStorage_perc_0
hw.vendor		Recommended	string	Vendor name of the hardware component	Dell; HP; Intel; AMD; LSI; Lenovo

Metric: hw.battery.charge.limit

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
hw.battery.charge.limit	Gauge	1	Lower limit of battery charge fraction to ensure proper operation.

Attributes:

Key	Stability	Requirement Level	Value Type	Description	Example Values
hw.id		Required	string	An identifier for the hardware component, unique within the monitored host	win32battery_battery_testsysa33_1
hw.battery.capacity		Recommended	string	Design capacity in Watts-hours or Ampere-hours	9.3Ah; 50Wh
hw.battery.chemistry		Recommended	string	Battery chemistry, e.g. Lithium-Ion, Nickel-Cadmium, etc.	Li-ion; NiMH
hw.limit_type		Recommended	string	Represents battery charge level thresholds relevant to device operation and health. Each limit_type denotes a specific charge limit such as the minimum or maximum optimal charge, the shutdown threshold, or energy-saving thresholds. These values are typically provided by the hardware or firmware to guide safe and efficient battery usage.	critical; throttled; degraded
hw.model		Recommended	string	Descriptive model name of the hardware component	PERC H740P; Intel(R) Core(TM) i7-10700K; Dell XPS 15 Battery
hw.name		Recommended	string	An easily-recognizable name for the hardware component	eth0
hw.parent		Recommended	string	Unique identifier of the parent component (typically the hw.id attribute of the enclosure, or disk controller)	dellStorage_perc_0
hw.vendor		Recommended	string	Vendor name of the hardware component	Dell; HP; Intel; AMD; LSI; Lenovo

---

hw.limit_type has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.

Value	Description	Stability
critical	Critical
degraded	Degraded
high.critical	High Critical
high.degraded	High Degraded
low.critical	Low Critical
low.degraded	Low Degraded
max	Maximum
throttled	Throttled
turbo	Turbo

Metric: hw.battery.time_left

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
hw.battery.time_left	Gauge	s	Time left before battery is completely charged or discharged.

Attributes:

Key	Stability	Requirement Level	Value Type	Description	Example Values
hw.id		Required	string	An identifier for the hardware component, unique within the monitored host	win32battery_battery_testsysa33_1
hw.state		Required	string	The current state of the component	degraded; failed; needs_cleaning
hw.battery.state		Conditionally Required If the battery is charging or discharging	string	The current state of the battery [1]	charging; discharging
hw.battery.capacity		Recommended	string	Design capacity in Watts-hours or Ampere-hours	9.3Ah; 50Wh
hw.battery.chemistry		Recommended	string	Battery chemistry, e.g. Lithium-Ion, Nickel-Cadmium, etc.	Li-ion; NiMH
hw.model		Recommended	string	Descriptive model name of the hardware component	PERC H740P; Intel(R) Core(TM) i7-10700K; Dell XPS 15 Battery
hw.name		Recommended	string	An easily-recognizable name for the hardware component	eth0
hw.parent		Recommended	string	Unique identifier of the parent component (typically the hw.id attribute of the enclosure, or disk controller)	dellStorage_perc_0
hw.vendor		Recommended	string	Vendor name of the hardware component	Dell; HP; Intel; AMD; LSI; Lenovo

[1] hw.battery.state: The hw.state attribute should indicate the current state of the battery. It should be one of the predefined states such as "charging" or "discharging".

---

hw.battery.state has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.

Value	Description	Stability
charging	Charging
discharging	Discharging

---

hw.state has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.

Value	Description	Stability
degraded	Degraded
failed	Failed
needs_cleaning	Needs Cleaning
ok	OK
predicted_failure	Predicted Failure

Metric: hw.status (Battery)

This metric is recommended.

Operational status: 1 (true) or 0 (false) for each of the possible states.

When using this metric for battery status, the following attributes MUST be set:

• hw.type MUST be set to "battery" to indicate that the status is for a battery.
• hw.state MUST be set to one of the following values to indicate the battery state:
  • "ok": The battery is operating normally.
  • "degraded": The battery is operating with reduced functionality or performance.
  • "failed": The battery has failed and is not operational.
  • "charging": The battery is currently charging.
  • "discharging": The battery is currently discharging.

The hw.type attribute should indicate the type of hardware component, which in this case is a battery. It should be set to "battery" to clearly identify the component being monitored.

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
hw.status	UpDownCounter	1	Operational status: 1 (true) or 0 (false) for each of the possible states. [1]

[1]: hw.status is currently specified as an UpDownCounter but would ideally be represented using a StateSet as defined in OpenMetrics. This semantic convention will be updated once StateSet is specified in OpenTelemetry. This planned change is not expected to have any consequence on the way users query their timeseries backend to retrieve the values of hw.status over time.

Attributes:

Key	Stability	Requirement Level	Value Type	Description	Example Values
hw.id		Required	string	An identifier for the hardware component, unique within the monitored host	win32battery_battery_testsysa33_1
hw.state		Required	string	The current state of the component	degraded; failed; needs_cleaning
hw.type		Required	string	Type of the component [1]	battery; cpu; disk_controller
hw.name		Recommended	string	An easily-recognizable name for the hardware component	eth0
hw.parent		Recommended	string	Unique identifier of the parent component (typically the hw.id attribute of the enclosure, or disk controller)	dellStorage_perc_0

[1] hw.type: Describes the category of the hardware component for which hw.state is being reported. For example, hw.type=temperature along with hw.state=degraded would indicate that the temperature of the hardware component has been reported as degraded.

---

hw.state has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.

Value	Description	Stability
degraded	Degraded
failed	Failed
needs_cleaning	Needs Cleaning
ok	OK
predicted_failure	Predicted Failure

---

hw.type has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.

Value	Description	Stability
battery	Battery
cpu	CPU
disk_controller	Disk controller
enclosure	Enclosure
fan	Fan
gpu	GPU
logical_disk	Logical disk
memory	Memory
network	Network
physical_disk	Physical disk
power_supply	Power supply
tape_drive	Tape drive
temperature	Temperature
voltage	Voltage