Semantic conventions for physical disk metrics

Status: Development

Physical disk metrics hw.physical_disk.*

Physical hard drive (HDD or SDD).

hw.type MUST be set to "physical_disk".

All physical disk 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.firmware_version	string	Firmware version of the hardware component	2.0.1	Recommended
hw.model	string	Descriptive model name of the hardware component	PERC H740P; Intel(R) Core(TM) i7-10700K; Dell XPS 15 Battery	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.physical_disk.type	string	Type of the physical disk	HDD; SSD; 10K	Recommended
hw.serial_number	string	Serial number of the hardware component	CNFCP0123456789	Recommended
hw.vendor	string	Vendor name of the hardware component	Dell; HP; Intel; AMD; LSI; Lenovo	Recommended

Metric: hw.errors (Physical Disk)

This metric is recommended.

Number of errors encountered on this disk.

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

• hw.type MUST be set to "physical_disk" to indicate that the errors are from a physical disk.

The following attributes SHOULD be set:

• error.type SHOULD be set to indicate the type of error, such as "bad_sector", "write", etc.

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
hw.errors	Counter	{error}	Number of errors encountered by the component.

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.type	string	Type of the component [1]	battery; cpu; disk_controller	Required
error.type	string	The type of error encountered by the component. [2]	uncorrected; zero_buffer_credit; crc; bad_sector	Conditionally Required if and only if an error has occurred
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
network.io.direction	string	Direction of network traffic for network errors. [3]	receive; transmit	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.

[2] error.type: The error.type SHOULD match the error code reported by the component, the canonical name of the error, or another low-cardinality error identifier. Instrumentations SHOULD document the list of errors they report.

[3] network.io.direction: This attribute SHOULD only be used when hw.type is set to "network" to indicate the direction of the error.

error.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
_OTHER	A fallback error value to be used when the instrumentation doesn’t define a custom value.

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

network.io.direction 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
receive	receive
transmit	transmit

Metric: hw.physical_disk.endurance_utilization

This metric is recommended.

Endurance remaining for this SSD disk.

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

• hw.physical_disk.state MUST be set to "remaining" to indicate the remaining endurance.

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
hw.physical_disk.endurance_utilization	Gauge	1	Endurance remaining for this SSD disk.

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.physical_disk.state	string	State of the physical disk endurance utilization	remaining	Required
hw.firmware_version	string	Firmware version of the hardware component	2.0.1	Recommended
hw.model	string	Descriptive model name of the hardware component	PERC H740P; Intel(R) Core(TM) i7-10700K; Dell XPS 15 Battery	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.physical_disk.type	string	Type of the physical disk	HDD; SSD; 10K	Recommended
hw.serial_number	string	Serial number of the hardware component	CNFCP0123456789	Recommended
hw.vendor	string	Vendor name of the hardware component	Dell; HP; Intel; AMD; LSI; Lenovo	Recommended

hw.physical_disk.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
remaining	Remaining

Metric: hw.physical_disk.size

This metric is recommended.

Size of the disk.

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
hw.physical_disk.size	UpDownCounter	By	Size of the disk.

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.firmware_version	string	Firmware version of the hardware component	2.0.1	Recommended
hw.model	string	Descriptive model name of the hardware component	PERC H740P; Intel(R) Core(TM) i7-10700K; Dell XPS 15 Battery	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.physical_disk.type	string	Type of the physical disk	HDD; SSD; 10K	Recommended
hw.serial_number	string	Serial number of the hardware component	CNFCP0123456789	Recommended
hw.vendor	string	Vendor name of the hardware component	Dell; HP; Intel; AMD; LSI; Lenovo	Recommended

Metric: hw.physical_disk.smart

This metric is recommended.

Value of the corresponding S.M.A.R.T. attribute.

The following attributes SHOULD be set:

• hw.physical_disk.smart_attribute SHOULD be set to indicate the specific S.M.A.R.T. attribute being reported, such as "Seek Error Rate", "Spin Retry Count", etc.

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
hw.physical_disk.smart	Gauge	1	Value of the corresponding S.M.A.R.T. (Self-Monitoring, Analysis, and Reporting Technology) attribute.

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.firmware_version	string	Firmware version of the hardware component	2.0.1	Recommended
hw.model	string	Descriptive model name of the hardware component	PERC H740P; Intel(R) Core(TM) i7-10700K; Dell XPS 15 Battery	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.physical_disk.smart_attribute	string	S.M.A.R.T. (Self-Monitoring, Analysis, and Reporting Technology) attribute of the physical disk	Spin Retry Count; Seek Error Rate	Recommended
hw.physical_disk.type	string	Type of the physical disk	HDD; SSD; 10K	Recommended
hw.serial_number	string	Serial number of the hardware component	CNFCP0123456789	Recommended
hw.vendor	string	Vendor name of the hardware component	Dell; HP; Intel; AMD; LSI; Lenovo	Recommended

Metric: hw.status (Physical Disk)

This metric is recommended.

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

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

• hw.type MUST be set to "physical_disk" to indicate that the status is for a physical disk.
• hw.state MUST be set to one of the following values to indicate the physical disk state:
  • "ok": The physical disk is operating normally.
  • "degraded": The physical disk is operating with reduced functionality or performance.
  • "failed": The physical disk has failed and is not operational.
  • "predicted_failure": The physical disk is currently operational but is predicted to fail soon.

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