semantic-conventions/docs/hardware/voltage.md

Semantic conventions for voltage metrics

Status: Development

• Voltage metrics hw.voltage.*
  • Metric: hw.voltage
  • Metric: hw.voltage.limit
  • Metric: hw.voltage.nominal
  • Metric: hw.status (Voltage)

Voltage metrics hw.voltage.*

A voltage sensor, either numeric or discrete.

hw.type MUST be set to "voltage" when using the common hw.status metric.

All voltage metrics may include the below attributes:

Attribute	Type	Description	Examples	Requirement Level	Stability
hw.id	string	An identifier for the hardware component, unique within the monitored host	win32battery_battery_testsysa33_1	Required
hw.name	string	An easily-recognizable name for the hardware component	eth0	Recommended
hw.parent	string	Unique identifier of the parent component (typically the hw.id attribute of the enclosure, or disk controller)	dellStorage_perc_0	Recommended
hw.sensor_location	string	Location of the sensor	cpu0; ps1; INLET; CPU0_DIE; AMBIENT; MOTHERBOARD; PS0 V3_3; MAIN_12V; CPU_VCORE	Recommended

Metric: hw.voltage

This metric is recommended.

Voltage measured by the sensor.

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
hw.voltage	Gauge	V	Voltage measured by the sensor.

Attribute	Type	Description	Examples	Requirement Level	Stability
hw.id	string	An identifier for the hardware component, unique within the monitored host	win32battery_battery_testsysa33_1	Required
hw.name	string	An easily-recognizable name for the hardware component	eth0	Recommended
hw.parent	string	Unique identifier of the parent component (typically the hw.id attribute of the enclosure, or disk controller)	dellStorage_perc_0	Recommended
hw.sensor_location	string	Location of the sensor	cpu0; ps1; INLET; CPU0_DIE; AMBIENT; MOTHERBOARD; PS0 V3_3; MAIN_12V; CPU_VCORE	Recommended

Metric: hw.voltage.limit

This metric is recommended.

Voltage limit in Volts.

The following attributes SHOULD be set:

• hw.voltage.limit_type SHOULD be set to indicate the type of limit, such as "low.critical", "low.degraded", "high.degraded", or "high.critical".

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
hw.voltage.limit	Gauge	V	Voltage limit in Volts.

Attribute	Type	Description	Examples	Requirement Level	Stability
hw.id	string	An identifier for the hardware component, unique within the monitored host	win32battery_battery_testsysa33_1	Required
hw.limit_type	string	Type of limit for hardware components	low.critical; low.degraded; high.degraded; high.critical	Recommended
hw.name	string	An easily-recognizable name for the hardware component	eth0	Recommended
hw.parent	string	Unique identifier of the parent component (typically the hw.id attribute of the enclosure, or disk controller)	dellStorage_perc_0	Recommended
hw.sensor_location	string	Location of the sensor	cpu0; ps1; INLET; CPU0_DIE; AMBIENT; MOTHERBOARD; PS0 V3_3; MAIN_12V; CPU_VCORE	Recommended

---

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.voltage.nominal

This metric is recommended.

Nominal (expected) voltage.

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
hw.voltage.nominal	Gauge	V	Nominal (expected) voltage.

Attribute	Type	Description	Examples	Requirement Level	Stability
hw.id	string	An identifier for the hardware component, unique within the monitored host	win32battery_battery_testsysa33_1	Required
hw.name	string	An easily-recognizable name for the hardware component	eth0	Recommended
hw.parent	string	Unique identifier of the parent component (typically the hw.id attribute of the enclosure, or disk controller)	dellStorage_perc_0	Recommended
hw.sensor_location	string	Location of the sensor	cpu0; ps1; INLET; CPU0_DIE; AMBIENT; MOTHERBOARD; PS0 V3_3; MAIN_12V; CPU_VCORE	Recommended

Metric: hw.status (Voltage)

This metric is recommended.

Whether the voltage is within normal range: 1 (true) or 0 (false) for each of the possible states.

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

• hw.type MUST be set to "voltage" to indicate that the status is for a voltage sensor.
• hw.state MUST be set to one of the following values to indicate the voltage state:
  • "ok": The voltage is within normal range.
  • "degraded": The voltage is outside the normal range but not critical.
  • "failed": The voltage is at a critical level.

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.

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

[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