# Semantic conventions for battery metrics LLMS index: [llms.txt](/llms.txt) --- **Status**: [Development][DocumentStatus] ## Battery metrics `hw.battery.*` A battery in a computer system or an UPS. `hw.type` MUST be set to `"battery"`. All battery metrics may include the below attributes to describe the characteristics of the monitored battery: **Attributes:** | Key | Stability | [Requirement Level](/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values | | --- | --- | --- | --- | --- | --- | | [`hw.id`](/docs/specs/semconv/registry/attributes/hardware.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Required` | string | An identifier for the hardware component, unique within the monitored host | `win32battery_battery_testsysa33_1` | | [`hw.battery.capacity`](/docs/specs/semconv/registry/attributes/hardware.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | Design capacity in Watts-hours or Amper-hours | `9.3Ah`; `50Wh` | | [`hw.battery.chemistry`](/docs/specs/semconv/registry/attributes/hardware.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | Battery [chemistry](https://schemas.dmtf.org/wbem/cim-html/2.31.0/CIM_Battery.html), e.g. Lithium-Ion, Nickel-Cadmium, etc. | `Li-ion`; `NiMH` | | [`hw.model`](/docs/specs/semconv/registry/attributes/hardware.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | Descriptive model name of the hardware component | `PERC H740P`; `Intel(R) Core(TM) i7-10700K`; `Dell XPS 15 Battery` | | [`hw.name`](/docs/specs/semconv/registry/attributes/hardware.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | An easily-recognizable name for the hardware component | `eth0` | | [`hw.parent`](/docs/specs/semconv/registry/attributes/hardware.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | Unique identifier of the parent component (typically the `hw.id` attribute of the enclosure, or disk controller) | `dellStorage_perc_0` | | [`hw.vendor`](/docs/specs/semconv/registry/attributes/hardware.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | Vendor name of the hardware component | `Dell`; `HP`; `Intel`; `AMD`; `LSI`; `Lenovo` | ### Metric: `hw.battery.charge` This metric is [recommended][MetricRecommended]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | | -------- | --------------- | ----------- | -------------- | --------- | ------ | | `hw.battery.charge` | Gauge | `1` | Remaining fraction of battery charge. | ![Development](https://img.shields.io/badge/-development-blue) | | **Attributes:** | Key | Stability | [Requirement Level](/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values | | --- | --- | --- | --- | --- | --- | | [`hw.id`](/docs/specs/semconv/registry/attributes/hardware.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Required` | string | An identifier for the hardware component, unique within the monitored host | `win32battery_battery_testsysa33_1` | | [`hw.battery.capacity`](/docs/specs/semconv/registry/attributes/hardware.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | Design capacity in Watts-hours or Amper-hours | `9.3Ah`; `50Wh` | | [`hw.battery.chemistry`](/docs/specs/semconv/registry/attributes/hardware.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | Battery [chemistry](https://schemas.dmtf.org/wbem/cim-html/2.31.0/CIM_Battery.html), e.g. Lithium-Ion, Nickel-Cadmium, etc. | `Li-ion`; `NiMH` | | [`hw.model`](/docs/specs/semconv/registry/attributes/hardware.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | Descriptive model name of the hardware component | `PERC H740P`; `Intel(R) Core(TM) i7-10700K`; `Dell XPS 15 Battery` | | [`hw.name`](/docs/specs/semconv/registry/attributes/hardware.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | An easily-recognizable name for the hardware component | `eth0` | | [`hw.parent`](/docs/specs/semconv/registry/attributes/hardware.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | Unique identifier of the parent component (typically the `hw.id` attribute of the enclosure, or disk controller) | `dellStorage_perc_0` | | [`hw.vendor`](/docs/specs/semconv/registry/attributes/hardware.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | Vendor name of the hardware component | `Dell`; `HP`; `Intel`; `AMD`; `LSI`; `Lenovo` | ### Metric: `hw.battery.charge.limit` This metric is [recommended][MetricRecommended]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | | -------- | --------------- | ----------- | -------------- | --------- | ------ | | `hw.battery.charge.limit` | Gauge | `1` | Lower limit of battery charge fraction to ensure proper operation. | ![Development](https://img.shields.io/badge/-development-blue) | | **Attributes:** | Key | Stability | [Requirement Level](/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values | | --- | --- | --- | --- | --- | --- | | [`hw.id`](/docs/specs/semconv/registry/attributes/hardware.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Required` | string | An identifier for the hardware component, unique within the monitored host | `win32battery_battery_testsysa33_1` | | [`hw.battery.capacity`](/docs/specs/semconv/registry/attributes/hardware.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | Design capacity in Watts-hours or Amper-hours | `9.3Ah`; `50Wh` | | [`hw.battery.chemistry`](/docs/specs/semconv/registry/attributes/hardware.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | Battery [chemistry](https://schemas.dmtf.org/wbem/cim-html/2.31.0/CIM_Battery.html), e.g. Lithium-Ion, Nickel-Cadmium, etc. | `Li-ion`; `NiMH` | | [`hw.limit_type`](/docs/specs/semconv/registry/attributes/hardware.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | Represents battery charge level thresholds relevant to device operation and health. Each `limit_type` denotes a specific charge limit such as the minimum or maximum optimal charge, the shutdown threshold, or energy-saving thresholds. These values are typically provided by the hardware or firmware to guide safe and efficient battery usage. | `critical`; `throttled`; `degraded` | | [`hw.model`](/docs/specs/semconv/registry/attributes/hardware.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | Descriptive model name of the hardware component | `PERC H740P`; `Intel(R) Core(TM) i7-10700K`; `Dell XPS 15 Battery` | | [`hw.name`](/docs/specs/semconv/registry/attributes/hardware.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | An easily-recognizable name for the hardware component | `eth0` | | [`hw.parent`](/docs/specs/semconv/registry/attributes/hardware.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | Unique identifier of the parent component (typically the `hw.id` attribute of the enclosure, or disk controller) | `dellStorage_perc_0` | | [`hw.vendor`](/docs/specs/semconv/registry/attributes/hardware.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | Vendor name of the hardware component | `Dell`; `HP`; `Intel`; `AMD`; `LSI`; `Lenovo` | --- `hw.limit_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 | | --- | --- | --- | | `critical` | Critical | ![Development](https://img.shields.io/badge/-development-blue) | | `degraded` | Degraded | ![Development](https://img.shields.io/badge/-development-blue) | | `high.critical` | High Critical | ![Development](https://img.shields.io/badge/-development-blue) | | `high.degraded` | High Degraded | ![Development](https://img.shields.io/badge/-development-blue) | | `low.critical` | Low Critical | ![Development](https://img.shields.io/badge/-development-blue) | | `low.degraded` | Low Degraded | ![Development](https://img.shields.io/badge/-development-blue) | | `max` | Maximum | ![Development](https://img.shields.io/badge/-development-blue) | | `throttled` | Throttled | ![Development](https://img.shields.io/badge/-development-blue) | | `turbo` | Turbo | ![Development](https://img.shields.io/badge/-development-blue) | ### Metric: `hw.battery.time_left` This metric is [recommended][MetricRecommended]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | | -------- | --------------- | ----------- | -------------- | --------- | ------ | | `hw.battery.time_left` | Gauge | `s` | Time left before battery is completely charged or discharged. | ![Development](https://img.shields.io/badge/-development-blue) | | **Attributes:** | Key | Stability | [Requirement Level](/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values | | --- | --- | --- | --- | --- | --- | | [`hw.id`](/docs/specs/semconv/registry/attributes/hardware.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Required` | string | An identifier for the hardware component, unique within the monitored host | `win32battery_battery_testsysa33_1` | | [`hw.state`](/docs/specs/semconv/registry/attributes/hardware.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Required` | string | The current state of the component | `degraded`; `failed`; `needs_cleaning` | | [`hw.battery.state`](/docs/specs/semconv/registry/attributes/hardware.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` If the battery is charging or discharging | string | The current state of the battery [1] | `charging`; `discharging` | | [`hw.battery.capacity`](/docs/specs/semconv/registry/attributes/hardware.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | Design capacity in Watts-hours or Amper-hours | `9.3Ah`; `50Wh` | | [`hw.battery.chemistry`](/docs/specs/semconv/registry/attributes/hardware.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | Battery [chemistry](https://schemas.dmtf.org/wbem/cim-html/2.31.0/CIM_Battery.html), e.g. Lithium-Ion, Nickel-Cadmium, etc. | `Li-ion`; `NiMH` | | [`hw.model`](/docs/specs/semconv/registry/attributes/hardware.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | Descriptive model name of the hardware component | `PERC H740P`; `Intel(R) Core(TM) i7-10700K`; `Dell XPS 15 Battery` | | [`hw.name`](/docs/specs/semconv/registry/attributes/hardware.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | An easily-recognizable name for the hardware component | `eth0` | | [`hw.parent`](/docs/specs/semconv/registry/attributes/hardware.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | Unique identifier of the parent component (typically the `hw.id` attribute of the enclosure, or disk controller) | `dellStorage_perc_0` | | [`hw.vendor`](/docs/specs/semconv/registry/attributes/hardware.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | Vendor name of the hardware component | `Dell`; `HP`; `Intel`; `AMD`; `LSI`; `Lenovo` | **[1] `hw.battery.state`:** The `hw.state` attribute should indicate the current state of the battery. It should be one of the predefined states such as "charging" or "discharging". --- `hw.battery.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 | | --- | --- | --- | | `charging` | Charging | ![Development](https://img.shields.io/badge/-development-blue) | | `discharging` | Discharging | ![Development](https://img.shields.io/badge/-development-blue) | --- `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 | ![Development](https://img.shields.io/badge/-development-blue) | | `failed` | Failed | ![Development](https://img.shields.io/badge/-development-blue) | | `needs_cleaning` | Needs Cleaning | ![Development](https://img.shields.io/badge/-development-blue) | | `ok` | OK | ![Development](https://img.shields.io/badge/-development-blue) | | `predicted_failure` | Predicted Failure | ![Development](https://img.shields.io/badge/-development-blue) | ### Metric: `hw.status` (Battery) This metric is [recommended][MetricRecommended]. Operational status: `1` (true) or `0` (false) for each of the possible states. When using this metric for battery status, the following attributes MUST be set: - `hw.type` MUST be set to `"battery"` to indicate that the status is for a battery. - `hw.state` MUST be set to one of the following values to indicate the battery state: - `"ok"`: The battery is operating normally. - `"degraded"`: The battery is operating with reduced functionality or performance. - `"failed"`: The battery has failed and is not operational. - `"charging"`: The battery is currently charging. - `"discharging"`: The battery is currently discharging. The `hw.type` attribute should indicate the type of hardware component, which in this case is a battery. It should be set to "battery" to clearly identify the component being monitored. | 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] | ![Development](https://img.shields.io/badge/-development-blue) | | **[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. **Attributes:** | Key | Stability | [Requirement Level](/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values | | --- | --- | --- | --- | --- | --- | | [`hw.id`](/docs/specs/semconv/registry/attributes/hardware.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Required` | string | An identifier for the hardware component, unique within the monitored host | `win32battery_battery_testsysa33_1` | | [`hw.state`](/docs/specs/semconv/registry/attributes/hardware.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Required` | string | The current state of the component | `degraded`; `failed`; `needs_cleaning` | | [`hw.type`](/docs/specs/semconv/registry/attributes/hardware.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Required` | string | Type of the component [1] | `battery`; `cpu`; `disk_controller` | | [`hw.name`](/docs/specs/semconv/registry/attributes/hardware.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | An easily-recognizable name for the hardware component | `eth0` | | [`hw.parent`](/docs/specs/semconv/registry/attributes/hardware.md) | ![Development](https://img.shields.io/badge/-development-blue) | `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 | ![Development](https://img.shields.io/badge/-development-blue) | | `failed` | Failed | ![Development](https://img.shields.io/badge/-development-blue) | | `needs_cleaning` | Needs Cleaning | ![Development](https://img.shields.io/badge/-development-blue) | | `ok` | OK | ![Development](https://img.shields.io/badge/-development-blue) | | `predicted_failure` | Predicted Failure | ![Development](https://img.shields.io/badge/-development-blue) | --- `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 | ![Development](https://img.shields.io/badge/-development-blue) | | `cpu` | CPU | ![Development](https://img.shields.io/badge/-development-blue) | | `disk_controller` | Disk controller | ![Development](https://img.shields.io/badge/-development-blue) | | `enclosure` | Enclosure | ![Development](https://img.shields.io/badge/-development-blue) | | `fan` | Fan | ![Development](https://img.shields.io/badge/-development-blue) | | `gpu` | GPU | ![Development](https://img.shields.io/badge/-development-blue) | | `logical_disk` | Logical disk | ![Development](https://img.shields.io/badge/-development-blue) | | `memory` | Memory | ![Development](https://img.shields.io/badge/-development-blue) | | `network` | Network | ![Development](https://img.shields.io/badge/-development-blue) | | `physical_disk` | Physical disk | ![Development](https://img.shields.io/badge/-development-blue) | | `power_supply` | Power supply | ![Development](https://img.shields.io/badge/-development-blue) | | `tape_drive` | Tape drive | ![Development](https://img.shields.io/badge/-development-blue) | | `temperature` | Temperature | ![Development](https://img.shields.io/badge/-development-blue) | | `voltage` | Voltage | ![Development](https://img.shields.io/badge/-development-blue) | [DocumentStatus]: /docs/specs/otel/document-status [MetricRecommended]: /docs/specs/semconv/general/metric-requirement-level.md#recommended