Semantic Conventions for Hardware Metrics
Status: Experimental
This document describes instruments and attributes for common hardware level metrics in OpenTelemetry. Consider the general metric semantic conventions when creating instruments not explicitly defined in the specification.
Common hardware attributes
All metrics in hw.
instruments should be attached to a Host Resource
and therefore inherit its attributes, like host.id
and host.name
.
Additionally, all metrics in hw.
instruments have the following attributes:
Attribute Key | Description | Example | Requirement Level |
---|---|---|---|
id |
An identifier for the hardware component, unique within the monitored host | win32battery_battery_testsysa33_1 |
Required |
name |
An easily-recognizable name for the hardware component | eth0 |
Recommended |
parent |
Unique identifier of the parent component (typically the id attribute of the enclosure, or disk controller) |
dellStorage_perc_0 |
Recommended |
Metric Instruments
hw.
- Common hardware metrics
The below metrics apply to any type of hardware component.
Name | Description | Units | Instrument Type (*) | Value Type | Attribute Key(s) | Attribute Values |
---|---|---|---|---|---|---|
hw.energy |
Energy consumed by the component, in joules | J | Counter | Int64 | ||
hw.errors |
Number of errors encountered by the component | {error} | Counter | Int64 | hw.error.type (Recommended) |
|
hw.power |
Instantaneous power consumed by the component, in Watts (hw.energy is preferred) |
W | Gauge | Double | ||
hw.status |
Operational status: 1 (true) or 0 (false) for each of the possible states |
UpDownCounter | Int | state (Required) |
ok , degraded , failed |
These common hw.
metrics must include the below attributes to describe the
monitored component:
Attribute Key | Description | Example | Requirement Level |
---|---|---|---|
hw.type |
Type of the component | battery , cpu , disk_controller , enclosure , fan , gpu , logical_disk , memory , network , physical_disk , power_supply , tape_drive , temperature , voltage |
Required |
Warning
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 ofhw.status
over time.
hw.host.
- Physical host metrics
Description: Physical system as opposed to a virtual system or a container. Examples: physical server, switch or disk array.
Name | Description | Units | Instrument Type (*) | Value Type | Attribute Key(s) | Attribute Values |
---|---|---|---|---|---|---|
hw.host.ambient_temperature |
Ambient (external) temperature of the physical host | Cel | Gauge | Double | ||
hw.host.energy |
Total energy consumed by the entire physical host, in joules | J | Counter | Int64 | ||
hw.host.heating_margin |
By how many degrees Celsius the temperature of the physical host can be increased, before reaching a warning threshold on one of the internal sensors | Cel | Gauge | Double | ||
hw.host.power |
Instantaneous power consumed by the entire physical host in Watts (hw.host.energy is preferred) |
W | Gauge | Double |
Note The overall energy usage of a host MUST be reported using the specific
hw.host.energy
andhw.host.power
metrics only, instead of the generichw.energy
andhw.power
described in the previous section, to prevent summing up overlapping values.
hw.battery.
- Battery metrics
Description: A battery in a computer system or an UPS.
Name | Description | Units | Instrument Type (*) | Value Type | Attribute Key(s) | Attribute Values |
---|---|---|---|---|---|---|
hw.battery.charge |
Remaining fraction of battery charge | 1 | Gauge | Double | ||
hw.battery.charge.limit |
Lower limit of battery charge fraction to ensure proper operation | 1 | Gauge | Double | limit_type (Recommended) |
critical , throttled , degraded |
hw.battery.time_left |
Time left before battery is completely charged or discharged | s | Gauge | Int | state (Conditionally Required, if the battery is charging or discharging) |
charging , discharging |
hw.status |
Operational status: 1 (true) or 0 (false) for each of the possible states |
UpDownCounter | Int | state (Required) |
ok , degraded , failed , charging , discharging |
|
hw.type |
battery |
All hw.battery.
metrics may include the below Recommended attributes to
describe the characteristics of the monitored battery:
Attribute Key | Description | Example |
---|---|---|
chemistry |
Chemistry of the battery | Nickel-Cadmium, Lithium-ion |
capacity |
Design capacity in Watts-hours or Amper-hours | 9.3Ah |
model |
Descriptive model name | |
vendor |
Vendor name |
hw.cpu.
- Physical processor metrics
Description: Physical processor (as opposed to the logical processor seen by the operating system for multi-core systems). A physical processor may include many individual cores.
Name | Description | Units | Instrument Type (*) | Value Type | Attribute Key | Attribute Values |
---|---|---|---|---|---|---|
hw.errors |
Total number of errors encountered and corrected by the CPU | {error} | Counter | Int64 | hw.type (Required) |
cpu |
hw.cpu.speed |
CPU current frequency | Hz | Gauge | Int64 | ||
hw.cpu.speed.limit |
CPU maximum frequency | Hz | Gauge | Int64 | limit_type (Recommended) |
throttled , max , turbo |
hw.status |
Operational status: 1 (true) or 0 (false) for each of the possible states |
UpDownCounter | Int | state (Required) |
ok , degraded , failed , predicted_failure |
|
hw.type (Required) |
cpu |
Additional Recommended attributes:
Attribute Key | Description | Example |
---|---|---|
model |
Descriptive model name | |
vendor |
Vendor name |
hw.disk_controller.
- Disk controller metrics
Description: Controller that controls the physical disks and organize them in RAID sets and logical disks that are exposed to the operating system.
Name | Description | Units | Instrument Type (*) | Value Type | Attribute Key | Attribute Values |
---|---|---|---|---|---|---|
hw.status |
Operational status: 1 (true) or 0 (false) for each of the possible states |
UpDownCounter | Int | state (Required) |
ok , degraded , failed |
|
hw.type (Required) |
disk_controller |
Additional Recommended attributes:
Attribute Key | Description | Example |
---|---|---|
bios_version |
BIOS version | |
driver_version |
Driver for the controller | |
firmware_version |
Firmware version | |
model |
Descriptive model name | |
serial_number |
Serial number | |
vendor |
Vendor name |
hw.enclosure.
- Enclosure metrics
Description: Computer chassis (can be an expansion enclosure)
Name | Description | Units | Instrument Type (*) | Value Type | Attribute Key | Attribute Values |
---|---|---|---|---|---|---|
hw.status |
Operational status: 1 (true) or 0 (false) for each of the possible states |
UpDownCounter | Int | state (Required) |
ok , degraded , failed , open |
|
hw.type (Required) |
enclosure |
Additional Recommended attributes:
Attribute Key | Description | Example |
---|---|---|
bios_version |
BIOS version | |
model |
Descriptive model name | |
serial_number |
Serial number | |
type |
Type of the enclosure (useful for modular systems) | Computer, Storage, Switch |
vendor |
Vendor name |
hw.fan.
- Fan metrics
Description: Fan that keeps the air flowing to maintain the internal temperature of a computer
Name | Description | Units | Instrument Type (*) | Value Type | Attribute Key | Attribute Values |
---|---|---|---|---|---|---|
hw.fan.speed |
Fan speed in revolutions per minute | rpm | Gauge | Int | ||
hw.fan.speed.limit |
Speed limit in rpm | rpm | Gauge | Int | limit_type (Recommended) |
low.critical , low.degraded , max |
hw.fan.speed_ratio |
Fan speed expressed as a fraction of its maximum speed | 1 | Gauge | Double | ||
hw.status |
Operational status: 1 (true) or 0 (false) for each of the possible states |
UpDownCounter | Int | state (Required) |
ok , degraded , failed |
|
hw.type (Required) |
fan |
Additional Recommended attributes:
Attribute Key | Description | Example |
---|---|---|
sensor_location |
Location of the fan in the computer enclosure | cpu0, ps1, INLET |
hw.gpu.
- GPU metrics
Description: Graphics Processing Unit (discrete)
Name | Description | Units | Instrument Type (*) | Value Type | Attribute Key | Attribute Values |
---|---|---|---|---|---|---|
hw.errors |
Number of errors encountered by the GPU | {error} | Counter | Int64 | hw.error.type (Recommended) |
corrected , uncorrected |
hw.type (Required) |
gpu |
|||||
hw.gpu.io |
Received and transmitted bytes by the GPU | By | Counter | Int64 | direction (Required) |
receive , transmit |
hw.gpu.memory.limit |
Size of the GPU memory | By | UpDownCounter | Int64 | ||
hw.gpu.memory.utilization |
Fraction of GPU memory used | 1 | Gauge | Double | ||
hw.gpu.memory.usage |
GPU memory used | By | UpDownCounter | Int64 | ||
hw.gpu.power |
GPU instantaneous power consumption in Watts | W | Gauge | Double | ||
hw.gpu.utilization |
Fraction of time spent in a specific task | 1 | Gauge | Double | task (Recommended) |
decoder , encoder , general |
hw.status |
Operational status: 1 (true) or 0 (false) for each of the possible states |
UpDownCounter | Int | state (Required) |
ok , degraded , failed , predicted_failure |
|
hw.type (Required) |
gpu |
Additional Recommended attributes:
Attribute Key | Description | Example |
---|---|---|
driver_version |
Driver for the controller | |
firmware_version |
Firmware version | |
model |
Descriptive model name | |
serial_number |
Serial number | |
vendor |
Vendor name |
hw.logical_disk.
- Logical disk metrics
Description: Storage extent presented as a physical disk by a disk controller to the operating system (e.g. a RAID 1 set made of 2 disks, and exposed as /dev/hdd0 by the controller).
Name | Description | Units | Instrument Type (*) | Value Type | Attribute Key | Attribute Values |
---|---|---|---|---|---|---|
hw.errors |
Number of errors encountered on this logical disk | {error} | Counter | Int64 | hw.type (Required) |
logical_disk |
hw.logical_disk.limit |
Size of the logical disk | By | UpDownCounter | Int64 | ||
hw.logical_disk.usage |
Logical disk space usage | By | UpDownCounter | Int64 | state (Required) |
used , free |
hw.logical_disk.utilization |
Logical disk space utilization as a fraction | 1 | Gauge | Double | state (Required) |
used , free |
hw.status |
Operational status: 1 (true) or 0 (false) for each of the possible states |
UpDownCounter | Int | state (Required) |
ok , degraded , failed |
|
hw.type (Required) |
logical_disk |
Additional Recommended attributes:
Attribute Key | Description | Example |
---|---|---|
raid_level |
RAID Level | RAID0+1 |
hw.memory.
- Memory module metrics
Description: A memory module in a computer system.
Name | Description | Units | Instrument Type (*) | Value Type | Attribute Key | Attribute Values |
---|---|---|---|---|---|---|
hw.errors |
Number of errors encountered on this memory module | {error} | Counter | Int64 | hw.type (Required) |
memory |
hw.memory.size |
Size of the memory module | By | UpDownCounter | Int64 | ||
hw.status |
Operational status: 1 (true) or 0 (false) for each of the possible states |
UpDownCounter | Int | state (Required) |
ok , degraded , failed , predicted_failure |
|
hw.type (Required) |
memory |
Additional Recommended attributes:
Attribute Key | Description | Example |
---|---|---|
model |
Descriptive model name | |
serial_number |
Serial number | |
type |
Type of the memory module | DDR5 |
vendor |
Vendor name |
hw.network.
- Network adapter metrics
Description: A physical network interface, or a network interface controller (NIC), excluding software-based virtual adapters and loopbacks. For example, a physical network interface on a server, switch, router or firewall, an HBA, a fiber channel port or a Wi-Fi adapter.
Name | Description | Units | Instrument Type (*) | Value Type | Attribute Key | Attribute Values |
---|---|---|---|---|---|---|
hw.errors |
Number of errors encountered by the network adapter | {error} | Counter | Int64 | hw.error.type (Recommended) |
zero_buffer_credit , crc , etc. |
hw.type (Required) |
network |
|||||
direction (Recommended) |
receive , transmit |
|||||
hw.network.bandwidth.limit |
Link speed | By/s | UpDownCounter | Int64 | ||
hw.network.bandwidth.utilization |
Utilization of the network bandwidth as a fraction | 1 | Gauge | Double | ||
hw.network.io |
Received and transmitted network traffic in bytes | By | Counter | Int64 | direction (Required) |
receive , transmit |
hw.network.packets |
Received and transmitted network traffic in packets (or frames) | {packet} | Counter | Int64 | direction (Required) |
receive , transmit |
hw.network.up |
Link status: 1 (up) or 0 (down) |
UpDownCounter | Int | |||
hw.status |
Operational status, regardless of the link status: 1 (true) or 0 (false) for each of the possible states |
UpDownCounter | Int | state (Required) |
ok , degraded , failed |
|
hw.type (Required) |
network |
Additional Recommended attributes:
Attribute Key | Description | Example |
---|---|---|
model |
Descriptive model name | |
logical_addresses |
Logical addresses of the adapter (e.g. IP address, or WWPN) | 172.16.8.21, 57.11.193.42 |
physical_address |
Physical address of the adapter (e.g. MAC address, or WWNN) | 00-90-F5-E9-7B-36 |
serial_number |
Serial number | |
vendor |
Vendor name |
hw.physical_disk.
- Physical disk metrics
Description: Physical hard drive (HDD or SDD)
Name | Description | Units | Instrument Type (*) | Value Type | Attribute Key | Attribute Values |
---|---|---|---|---|---|---|
hw.errors |
Number of errors encountered on this disk | {error} | Counter | Int64 | hw.error.type (Recommended) |
bad_sector , write , etc. |
hw.type (Required) |
physical_disk |
|||||
hw.physical_disk.endurance_utilization |
Endurance remaining for this SSD disk | 1 | Gauge | Double | state (Required) |
remaining |
hw.physical_disk.size |
Size of the disk | By | UpDownCounter | Int64 | ||
hw.physical_disk.smart |
Value of the corresponding S.M.A.R.T. attribute | 1 | Gauge | Int | smart_attribute (Recommended) |
Seek Error Rate , Spin Retry Count , etc. |
hw.status |
Operational status: 1 (true) or 0 (false) for each of the possible states |
UpDownCounter | Int | state (Required) |
ok , degraded , failed , predicted_failure |
|
hw.type (Required) |
physical_disk |
Additional Recommended attributes:
Attribute Key | Description | Example |
---|---|---|
firmware_version |
Firmware version | |
model |
Descriptive model name | |
serial_number |
Serial number | |
type |
Type of the disk | HDD , SSD , 10K |
vendor |
Vendor name |
hw.power_supply.
- Power supply metrics
Description: Power supply converting AC current to DC used by the motherboard and the GPUs
Name | Description | Units | Instrument Type (*) | Value Type | Attribute Key | Attribute Values |
---|---|---|---|---|---|---|
hw.power_supply.limit |
Maximum power output of the power supply | W | UpDownCounter | Int64 | limit_type (Recommended) |
max , critical , throttled |
hw.power_supply.utilization |
Utilization of the power supply as a fraction of its maximum output | 1 | Gauge | Double | ||
hw.status |
Operational status: 1 (true) or 0 (false) for each of the possible states |
UpDownCounter | Int | state (Required) |
ok , degraded , failed |
|
hw.type (Required) |
power_supply |
Additional Recommended attributes:
Attribute Key | Description | Example |
---|---|---|
model |
Descriptive model name | |
serial_number |
Serial number | |
vendor |
Vendor name |
hw.tape_drive.
- Tape drive metrics
Description: A tape drive in a computer or in a tape library (excluding virtual tape libraries)
Name | Description | Units | Instrument Type (*) | Value Type | Attribute Key | Attribute Values |
---|---|---|---|---|---|---|
hw.errors |
Number of errors encountered by the tape drive | {error} | Counter | Int64 | hw.error.type |
read , write , mount , etc. |
hw.type (Required) |
tape_drive |
|||||
hw.tape_drive.operations |
Operations performed by the tape drive | {operation} | Counter | Int64 | type (Recommended) |
mount , unmount , clean |
hw.status |
Operational status: 1 (true) or 0 (false) for each of the possible states |
UpDownCounter | Int | state (Required) |
ok , degraded , failed , needs_cleaning |
|
hw.type (Required) |
tape_drive |
Additional Recommended attributes:
Attribute Key | Description | Example |
---|---|---|
model |
Descriptive model name | |
serial_number |
Serial number | |
vendor |
Vendor name |
hw.temperature.
- Temperature sensor metrics
Description: A temperature sensor, either numeric or discrete
Name | Description | Units | Instrument Type (*) | Value Type | Attribute Key | Attribute Values |
---|---|---|---|---|---|---|
hw.temperature |
Temperature in degrees Celsius | Cel | Gauge | Double | ||
hw.temperature.limit |
Temperature limit in degrees Celsius | Cel | Gauge | Double | limit_type (Recommended) |
low.critical , low.degraded , high.degraded , high.critical |
hw.status |
Whether the temperature is within normal range: 1 (true) or 0 (false) for each of the possible states |
UpDownCounter | Int | state (Required) |
ok , degraded , failed |
|
hw.type (Required) |
temperature |
Additional Recommended attributes:
Attribute Key | Description | Example |
---|---|---|
sensor_location |
Location of the sensor | CPU0_DIE |
hw.voltage.
- Voltage sensor metrics
Description: A voltage sensor, either numeric or discrete
Name | Description | Units | Instrument Type (*) | Value Type | Attribute Key | Attribute Values |
---|---|---|---|---|---|---|
hw.voltage.limit |
Voltage limit in Volts | V | Gauge | Double | limit_type (Recommended) |
low.critical , low.degraded , high.degraded , high.critical |
hw.voltage.nominal |
Nominal (expected) voltage | V | Gauge | Double | ||
hw.voltage |
Voltage measured by the sensor | V | Gauge | Double | ||
hw.status |
Whether the voltage is within normal range: 1 (true) or 0 (false) for each of the possible states |
UpDownCounter | Int | state (Required) |
ok , degraded , failed |
|
hw.type (Required) |
voltage |
Additional Recommended attributes:
Attribute Key | Description | Example |
---|---|---|
sensor_location |
Location of the sensor | PS0 V3_3 |