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.

Warning Existing instrumentations and collector that are using v1.21.0 of this document (or prior):
SHOULD NOT adopt any breaking changes from document until the system semantic conventions are marked stable. Conventions include, but are not limited to, attributes, metric names, and unit of measure.
SHOULD introduce a control mechanism to allow users to opt-in to the new conventions once the migration plan is finalized.

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 of hw.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
`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 and hw.host.power metrics only, instead of the generic hw.energy and hw.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`