# Semantic conventions for physical disk metrics **Status**: [Development][DocumentStatus] - [Physical disk metrics `hw.physical_disk.*`](#physical-disk-metrics-hwphysical_disk) - [Metric: `hw.errors` (Physical Disk)](#metric-hwerrors-physical-disk) - [Metric: `hw.physical_disk.endurance_utilization`](#metric-hwphysical_diskendurance_utilization) - [Metric: `hw.physical_disk.size`](#metric-hwphysical_disksize) - [Metric: `hw.physical_disk.smart`](#metric-hwphysical_disksmart) - [Metric: `hw.status` (Physical Disk)](#metric-hwstatus-physical-disk) ## 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](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`hw.id`](/docs/registry/attributes/hardware.md) | string | An identifier for the hardware component, unique within the monitored host | `win32battery_battery_testsysa33_1` | `Required` |  | | [`hw.firmware_version`](/docs/registry/attributes/hardware.md) | string | Firmware version of the hardware component | `2.0.1` | `Recommended` |  | | [`hw.model`](/docs/registry/attributes/hardware.md) | string | Descriptive model name of the hardware component | `PERC H740P`; `Intel(R) Core(TM) i7-10700K`; `Dell XPS 15 Battery` | `Recommended` |  | | [`hw.name`](/docs/registry/attributes/hardware.md) | string | An easily-recognizable name for the hardware component | `eth0` | `Recommended` |  | | [`hw.parent`](/docs/registry/attributes/hardware.md) | 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`](/docs/registry/attributes/hardware.md) | string | Type of the physical disk | `HDD`; `SSD`; `10K` | `Recommended` |  | | [`hw.serial_number`](/docs/registry/attributes/hardware.md) | string | Serial number of the hardware component | `CNFCP0123456789` | `Recommended` |  | | [`hw.vendor`](/docs/registry/attributes/hardware.md) | string | Vendor name of the hardware component | `Dell`; `HP`; `Intel`; `AMD`; `LSI`; `Lenovo` | `Recommended` |  | ### Metric: `hw.errors` (Physical Disk) This metric is [recommended][MetricRecommended]. 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](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`hw.id`](/docs/registry/attributes/hardware.md) | string | An identifier for the hardware component, unique within the monitored host | `win32battery_battery_testsysa33_1` | `Required` |  | | [`hw.type`](/docs/registry/attributes/hardware.md) | string | Type of the component [1] | `battery`; `cpu`; `disk_controller` | `Required` |  | | [`error.type`](/docs/registry/attributes/error.md) | 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`](/docs/registry/attributes/hardware.md) | string | An easily-recognizable name for the hardware component | `eth0` | `Recommended` |  | | [`hw.parent`](/docs/registry/attributes/hardware.md) | 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`](/docs/registry/attributes/network.md) | 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][MetricRecommended]. 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](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`hw.id`](/docs/registry/attributes/hardware.md) | string | An identifier for the hardware component, unique within the monitored host | `win32battery_battery_testsysa33_1` | `Required` |  | | [`hw.physical_disk.state`](/docs/registry/attributes/hardware.md) | string | State of the physical disk endurance utilization | `remaining` | `Required` |  | | [`hw.firmware_version`](/docs/registry/attributes/hardware.md) | string | Firmware version of the hardware component | `2.0.1` | `Recommended` |  | | [`hw.model`](/docs/registry/attributes/hardware.md) | string | Descriptive model name of the hardware component | `PERC H740P`; `Intel(R) Core(TM) i7-10700K`; `Dell XPS 15 Battery` | `Recommended` |  | | [`hw.name`](/docs/registry/attributes/hardware.md) | string | An easily-recognizable name for the hardware component | `eth0` | `Recommended` |  | | [`hw.parent`](/docs/registry/attributes/hardware.md) | 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`](/docs/registry/attributes/hardware.md) | string | Type of the physical disk | `HDD`; `SSD`; `10K` | `Recommended` |  | | [`hw.serial_number`](/docs/registry/attributes/hardware.md) | string | Serial number of the hardware component | `CNFCP0123456789` | `Recommended` |  | | [`hw.vendor`](/docs/registry/attributes/hardware.md) | 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][MetricRecommended]. 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](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`hw.id`](/docs/registry/attributes/hardware.md) | string | An identifier for the hardware component, unique within the monitored host | `win32battery_battery_testsysa33_1` | `Required` |  | | [`hw.firmware_version`](/docs/registry/attributes/hardware.md) | string | Firmware version of the hardware component | `2.0.1` | `Recommended` |  | | [`hw.model`](/docs/registry/attributes/hardware.md) | string | Descriptive model name of the hardware component | `PERC H740P`; `Intel(R) Core(TM) i7-10700K`; `Dell XPS 15 Battery` | `Recommended` |  | | [`hw.name`](/docs/registry/attributes/hardware.md) | string | An easily-recognizable name for the hardware component | `eth0` | `Recommended` |  | | [`hw.parent`](/docs/registry/attributes/hardware.md) | 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`](/docs/registry/attributes/hardware.md) | string | Type of the physical disk | `HDD`; `SSD`; `10K` | `Recommended` |  | | [`hw.serial_number`](/docs/registry/attributes/hardware.md) | string | Serial number of the hardware component | `CNFCP0123456789` | `Recommended` |  | | [`hw.vendor`](/docs/registry/attributes/hardware.md) | string | Vendor name of the hardware component | `Dell`; `HP`; `Intel`; `AMD`; `LSI`; `Lenovo` | `Recommended` |  | ### Metric: `hw.physical_disk.smart` This metric is [recommended][MetricRecommended]. Value of the corresponding [S.M.A.R.T.](https://wikipedia.org/wiki/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.](https://wikipedia.org/wiki/S.M.A.R.T.) (Self-Monitoring, Analysis, and Reporting Technology) attribute. |  | | | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`hw.id`](/docs/registry/attributes/hardware.md) | string | An identifier for the hardware component, unique within the monitored host | `win32battery_battery_testsysa33_1` | `Required` |  | | [`hw.firmware_version`](/docs/registry/attributes/hardware.md) | string | Firmware version of the hardware component | `2.0.1` | `Recommended` |  | | [`hw.model`](/docs/registry/attributes/hardware.md) | string | Descriptive model name of the hardware component | `PERC H740P`; `Intel(R) Core(TM) i7-10700K`; `Dell XPS 15 Battery` | `Recommended` |  | | [`hw.name`](/docs/registry/attributes/hardware.md) | string | An easily-recognizable name for the hardware component | `eth0` | `Recommended` |  | | [`hw.parent`](/docs/registry/attributes/hardware.md) | 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`](/docs/registry/attributes/hardware.md) | string | [S.M.A.R.T.](https://wikipedia.org/wiki/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`](/docs/registry/attributes/hardware.md) | string | Type of the physical disk | `HDD`; `SSD`; `10K` | `Recommended` |  | | [`hw.serial_number`](/docs/registry/attributes/hardware.md) | string | Serial number of the hardware component | `CNFCP0123456789` | `Recommended` |  | | [`hw.vendor`](/docs/registry/attributes/hardware.md) | string | Vendor name of the hardware component | `Dell`; `HP`; `Intel`; `AMD`; `LSI`; `Lenovo` | `Recommended` |  | ### Metric: `hw.status` (Physical Disk) This metric is [recommended][MetricRecommended]. 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](https://github.com/prometheus/OpenMetrics/blob/v1.0.0/specification/OpenMetrics.md#stateset). 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](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`hw.id`](/docs/registry/attributes/hardware.md) | string | An identifier for the hardware component, unique within the monitored host | `win32battery_battery_testsysa33_1` | `Required` |  | | [`hw.state`](/docs/registry/attributes/hardware.md) | string | The current state of the component | `degraded`; `failed`; `needs_cleaning` | `Required` |  | | [`hw.type`](/docs/registry/attributes/hardware.md) | string | Type of the component [1] | `battery`; `cpu`; `disk_controller` | `Required` |  | | [`hw.name`](/docs/registry/attributes/hardware.md) | string | An easily-recognizable name for the hardware component | `eth0` | `Recommended` |  | | [`hw.parent`](/docs/registry/attributes/hardware.md) | 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 |  | [DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status [MetricRecommended]: /docs/general/metric-requirement-level.md#recommended