Semantic conventions for GPU metrics

Status: Development

• GPU metrics hw.gpu.*
  • Metric: hw.errors (GPU)
  • Metric: hw.gpu.io
  • Metric: hw.gpu.memory.limit
  • Metric: hw.gpu.memory.utilization
  • Metric: hw.gpu.memory.usage
  • Metric: hw.gpu.utilization
  • Metric: hw.status (GPU)

GPU metrics hw.gpu.*

Graphics Processing Unit (discrete).

Metric: hw.errors (GPU)

This metric is recommended.

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

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.type		Required	string	Type of the component [1]	gpu
error.type		Conditionally Required if and only if an error has occurred	string	The type of error encountered by the component. [2]	corrected; uncorrected
hw.driver_version		Recommended	string	Driver version for the hardware component	10.2.1-3
hw.firmware_version		Recommended	string	Firmware version of the hardware component	2.0.1
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.serial_number		Recommended	string	Serial number of the hardware component	CNFCP0123456789
hw.vendor		Recommended	string	Vendor name of the hardware component	Dell; HP; Intel; AMD; LSI; Lenovo

[1] hw.type: MUST be set to gpu.

[2] error.type: error.type SHOULD be set to one of the following values to indicate the type of error:

• corrected: Errors that were detected and corrected by the GPU.
• uncorrected: Errors that were detected but could not be corrected by the GPU.

---

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

Metric: hw.gpu.io

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
hw.gpu.io	Counter	By	Received and transmitted bytes by the GPU.

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
network.io.direction		Required	string	The direction of traffic from the perspective of the observing host's physical or virtual network interface. It should not be used to represent the logical direction of a stateful connection or network flow.	receive; transmit
hw.driver_version		Recommended	string	Driver version for the hardware component	10.2.1-3
hw.firmware_version		Recommended	string	Firmware version of the hardware component	2.0.1
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.serial_number		Recommended	string	Serial number of the hardware component	CNFCP0123456789
hw.vendor		Recommended	string	Vendor name of the hardware component	Dell; HP; Intel; AMD; LSI; Lenovo

---

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.gpu.memory.limit

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
hw.gpu.memory.limit	UpDownCounter	By	Size of the GPU memory.

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.driver_version		Recommended	string	Driver version for the hardware component	10.2.1-3
hw.firmware_version		Recommended	string	Firmware version of the hardware component	2.0.1
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.serial_number		Recommended	string	Serial number of the hardware component	CNFCP0123456789
hw.vendor		Recommended	string	Vendor name of the hardware component	Dell; HP; Intel; AMD; LSI; Lenovo

Metric: hw.gpu.memory.utilization

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
hw.gpu.memory.utilization	Gauge	1	Fraction of GPU memory used.

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.driver_version		Recommended	string	Driver version for the hardware component	10.2.1-3
hw.firmware_version		Recommended	string	Firmware version of the hardware component	2.0.1
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.serial_number		Recommended	string	Serial number of the hardware component	CNFCP0123456789
hw.vendor		Recommended	string	Vendor name of the hardware component	Dell; HP; Intel; AMD; LSI; Lenovo

Metric: hw.gpu.memory.usage

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
hw.gpu.memory.usage	UpDownCounter	By	GPU memory used.

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.driver_version		Recommended	string	Driver version for the hardware component	10.2.1-3
hw.firmware_version		Recommended	string	Firmware version of the hardware component	2.0.1
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.serial_number		Recommended	string	Serial number of the hardware component	CNFCP0123456789
hw.vendor		Recommended	string	Vendor name of the hardware component	Dell; HP; Intel; AMD; LSI; Lenovo

Metric: hw.gpu.utilization

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
hw.gpu.utilization	Gauge	1	Fraction of time spent in a specific task.

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.driver_version		Recommended	string	Driver version for the hardware component	10.2.1-3
hw.firmware_version		Recommended	string	Firmware version of the hardware component	2.0.1
hw.gpu.task		Recommended	string	Type of task the GPU is performing	decoder; encoder; general
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.serial_number		Recommended	string	Serial number of the hardware component	CNFCP0123456789
hw.vendor		Recommended	string	Vendor name of the hardware component	Dell; HP; Intel; AMD; LSI; Lenovo

---

hw.gpu.task 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
decoder	Decoder
encoder	Encoder
general	General

Metric: hw.status (GPU)

This metric is recommended.

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 [1]	ok; degraded; failed; predicted_failure
hw.type		Required	string	Type of the component [2]	gpu
hw.driver_version		Recommended	string	Driver version for the hardware component	10.2.1-3
hw.firmware_version		Recommended	string	Firmware version of the hardware component	2.0.1
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.serial_number		Recommended	string	Serial number of the hardware component	CNFCP0123456789
hw.vendor		Recommended	string	Vendor name of the hardware component	Dell; HP; Intel; AMD; LSI; Lenovo

[1] hw.state: MUST be set to one of the following values:

• ok: The GPU is operating normally.
• degraded: The GPU is operating with reduced functionality or performance.
• failed: The GPU has failed and is not operational.
• predicted_failure: The GPU is currently operational but is predicted to fail soon.

[2] hw.type: MUST be set to gpu.

---

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