Semantic conventions for network metrics

Status: Development

Network metrics hw.network.*

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.

hw.type MUST be set to "network".

All network metrics may include the below attributes:

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.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.network.logical_addresses		Recommended	string[]	Logical addresses of the adapter (e.g. IP address, or WWPN)	["172.16.8.21", "57.11.193.42"]
hw.network.physical_address		Recommended	string	Physical address of the adapter (e.g. MAC address, or WWNN)	00-90-F5-E9-7B-36
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.errors (Network)

This metric is recommended.

Number of errors encountered by the network adapter.

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

• hw.type MUST be set to "network" to indicate that the errors are from a network adapter.

The following attributes SHOULD be set:

• error.type SHOULD be set to indicate the type of error, such as "zero_buffer_credit", "crc", etc.
• hw.network.direction SHOULD be set to indicate the direction of the error, either "receive" or "transmit".

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

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

[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.network.bandwidth.limit

This metric is recommended.

Link speed.

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
hw.network.bandwidth.limit	UpDownCounter	By/s	Link speed.

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.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.network.logical_addresses		Recommended	string[]	Logical addresses of the adapter (e.g. IP address, or WWPN)	["172.16.8.21", "57.11.193.42"]
hw.network.physical_address		Recommended	string	Physical address of the adapter (e.g. MAC address, or WWNN)	00-90-F5-E9-7B-36
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.network.bandwidth.utilization

This metric is recommended.

Utilization of the network bandwidth as a fraction.

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
hw.network.bandwidth.utilization	Gauge	1	Utilization of the network bandwidth as a fraction.

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.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.network.logical_addresses		Recommended	string[]	Logical addresses of the adapter (e.g. IP address, or WWPN)	["172.16.8.21", "57.11.193.42"]
hw.network.physical_address		Recommended	string	Physical address of the adapter (e.g. MAC address, or WWNN)	00-90-F5-E9-7B-36
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.network.io

This metric is recommended.

Received and transmitted network traffic in bytes.

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

• hw.network.direction MUST be set to one of the following values:
  • "receive": The amount of network traffic received.
  • "transmit": The amount of network traffic transmitted.

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
hw.network.io	Counter	By	Received and transmitted network traffic in bytes.

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 network IO operation direction.	receive; transmit
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.network.logical_addresses		Recommended	string[]	Logical addresses of the adapter (e.g. IP address, or WWPN)	["172.16.8.21", "57.11.193.42"]
hw.network.physical_address		Recommended	string	Physical address of the adapter (e.g. MAC address, or WWNN)	00-90-F5-E9-7B-36
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.network.packets

This metric is recommended.

Received and transmitted network traffic in packets (or frames).

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

• hw.network.direction MUST be set to one of the following values:
  • "receive": The number of packets received.
  • "transmit": The number of packets transmitted.

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
hw.network.packets	Counter	{packet}	Received and transmitted network traffic in packets (or frames).

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 network IO operation direction.	receive; transmit
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.network.logical_addresses		Recommended	string[]	Logical addresses of the adapter (e.g. IP address, or WWPN)	["172.16.8.21", "57.11.193.42"]
hw.network.physical_address		Recommended	string	Physical address of the adapter (e.g. MAC address, or WWNN)	00-90-F5-E9-7B-36
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.network.up

This metric is recommended.

Link status: 1 (up) or 0 (down).

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
hw.network.up	UpDownCounter	1	Link status: 1 (up) or 0 (down).

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.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.network.logical_addresses		Recommended	string[]	Logical addresses of the adapter (e.g. IP address, or WWPN)	["172.16.8.21", "57.11.193.42"]
hw.network.physical_address		Recommended	string	Physical address of the adapter (e.g. MAC address, or WWNN)	00-90-F5-E9-7B-36
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.status (Network)

This metric is recommended.

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

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

• hw.type MUST be set to "network" to indicate that the status is for a network adapter.
• hw.state MUST be set to one of the following values to indicate the network adapter state:
  • "ok": The network adapter is operating normally.
  • "degraded": The network adapter is operating with reduced functionality or performance.
  • "failed": The network adapter has failed and is not operational.

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	degraded; failed; needs_cleaning
hw.type		Required	string	Type of the component [1]	battery; cpu; disk_controller
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

[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