open-telemetry
/
semantic-conventions
mirror of https://github.com/open-telemetry/semantic-conventions.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
semantic-conventions/docs/hardware/common.md

299 lines
21 KiB
Markdown
Raw Blame History

<!--- Hugo front matter used to generate the website version of this page:
linkTitle: Common Hardware Metrics
--->
# Semantic Conventions for Common Hardware Metrics
**Status**: [Experimental][DocumentStatus]
<!-- toc -->
- [Common hardware metrics](#common-hardware-metrics)
- [Metric: `hw.energy`](#metric-hwenergy)
- [Metric: `hw.errors`](#metric-hwerrors)
- [Metric: `hw.power`](#metric-hwpower)
- [Metric: `hw.status`](#metric-hwstatus)
<!-- tocstop -->
Hardware metrics do not include attributes that identify the device, machine, or host they are reported for. This
information is expected to be provided via resource attributes configured by user applications.
Application developers are encouraged to configure [Host](/docs/resource/host.md) resource attributes.
## Common hardware metrics
The below metrics apply to any type of hardware component.
These common `hw.` metrics include the below attributes to describe the
monitored component:
<!-- semconv metric.hw.attributes -->
<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
<!-- see templates/registry/markdown/snippet.md.j2 -->
<!-- prettier-ignore-start -->
<!-- markdownlint-capture -->
<!-- markdownlint-disable -->
| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
|---|---|---|---|---|---|
| [`hw.id`](/docs/attributes-registry/hardware.md) | string | An identifier for the hardware component, unique within the monitored host | `win32battery_battery_testsysa33_1` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| [`hw.type`](/docs/attributes-registry/hardware.md) | string | Type of the component [1] | `battery`; `cpu`; `disk_controller` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| [`hw.name`](/docs/attributes-registry/hardware.md) | string | An easily-recognizable name for the hardware component | `eth0` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| [`hw.parent`](/docs/attributes-registry/hardware.md) | string | Unique identifier of the parent component (typically the `hw.id` attribute of the enclosure, or disk controller) | `dellStorage_perc_0` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
**[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.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 | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `cpu` | CPU | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `disk_controller` | Disk controller | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `enclosure` | Enclosure | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `fan` | Fan | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `gpu` | GPU | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `logical_disk` | Logical disk | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `memory` | Memory | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `network` | Network | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `physical_disk` | Physical disk | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `power_supply` | Power supply | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `tape_drive` | Tape drive | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `temperature` | Temperature | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `voltage` | Voltage | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
<!-- markdownlint-restore -->
<!-- prettier-ignore-end -->
<!-- END AUTOGENERATED TEXT -->
<!-- endsemconv -->
### Metric: `hw.energy`
This metric is [recommended][MetricRecommended].
<!-- semconv metric.hw.energy -->
<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
<!-- see templates/registry/markdown/snippet.md.j2 -->
<!-- prettier-ignore-start -->
<!-- markdownlint-capture -->
<!-- markdownlint-disable -->
| Name | Instrument Type | Unit (UCUM) | Description | Stability |
| -------- | --------------- | ----------- | -------------- | --------- |
| `hw.energy` | Counter | `J` | Energy consumed by the component | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
|---|---|---|---|---|---|
| [`hw.id`](/docs/attributes-registry/hardware.md) | string | An identifier for the hardware component, unique within the monitored host | `win32battery_battery_testsysa33_1` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| [`hw.type`](/docs/attributes-registry/hardware.md) | string | Type of the component [1] | `battery`; `cpu`; `disk_controller` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| [`hw.name`](/docs/attributes-registry/hardware.md) | string | An easily-recognizable name for the hardware component | `eth0` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| [`hw.parent`](/docs/attributes-registry/hardware.md) | string | Unique identifier of the parent component (typically the `hw.id` attribute of the enclosure, or disk controller) | `dellStorage_perc_0` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
**[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.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 | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `cpu` | CPU | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `disk_controller` | Disk controller | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `enclosure` | Enclosure | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `fan` | Fan | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `gpu` | GPU | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `logical_disk` | Logical disk | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `memory` | Memory | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `network` | Network | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `physical_disk` | Physical disk | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `power_supply` | Power supply | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `tape_drive` | Tape drive | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `temperature` | Temperature | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `voltage` | Voltage | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
<!-- markdownlint-restore -->
<!-- prettier-ignore-end -->
<!-- END AUTOGENERATED TEXT -->
<!-- endsemconv -->
### Metric: `hw.errors`
This metric is [recommended][MetricRecommended].
<!-- semconv metric.hw.errors -->
<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
<!-- see templates/registry/markdown/snippet.md.j2 -->
<!-- prettier-ignore-start -->
<!-- markdownlint-capture -->
<!-- markdownlint-disable -->
| Name | Instrument Type | Unit (UCUM) | Description | Stability |
| -------- | --------------- | ----------- | -------------- | --------- |
| `hw.errors` | Counter | `{error}` | Number of errors encountered by the component | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
|---|---|---|---|---|---|
| [`hw.id`](/docs/attributes-registry/hardware.md) | string | An identifier for the hardware component, unique within the monitored host | `win32battery_battery_testsysa33_1` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| [`hw.type`](/docs/attributes-registry/hardware.md) | string | Type of the component [1] | `battery`; `cpu`; `disk_controller` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| [`error.type`](/docs/attributes-registry/error.md) | string | The type of error encountered by the component [2] | `uncorrected`; `zero_buffer_credit`; `crc`; `bad_sector` | `Conditionally Required` if and only if an error has occurred | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |
| [`hw.name`](/docs/attributes-registry/hardware.md) | string | An easily-recognizable name for the hardware component | `eth0` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| [`hw.parent`](/docs/attributes-registry/hardware.md) | string | Unique identifier of the parent component (typically the `hw.id` attribute of the enclosure, or disk controller) | `dellStorage_perc_0` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
**[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.
---
`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. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |
---
`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 | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `cpu` | CPU | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `disk_controller` | Disk controller | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `enclosure` | Enclosure | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `fan` | Fan | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `gpu` | GPU | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `logical_disk` | Logical disk | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `memory` | Memory | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `network` | Network | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `physical_disk` | Physical disk | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `power_supply` | Power supply | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `tape_drive` | Tape drive | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `temperature` | Temperature | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `voltage` | Voltage | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
<!-- markdownlint-restore -->
<!-- prettier-ignore-end -->
<!-- END AUTOGENERATED TEXT -->
<!-- endsemconv -->
### Metric: `hw.power`
This metric is [recommended][MetricRecommended].
<!-- semconv metric.hw.power -->
<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
<!-- see templates/registry/markdown/snippet.md.j2 -->
<!-- prettier-ignore-start -->
<!-- markdownlint-capture -->
<!-- markdownlint-disable -->
| Name | Instrument Type | Unit (UCUM) | Description | Stability |
| -------- | --------------- | ----------- | -------------- | --------- |
| `hw.power` | Gauge | `W` | Instantaneous power consumed by the component [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
**[1]:** It is recommended to report `hw.energy` instead of `hw.power` when possible.
| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
|---|---|---|---|---|---|
| [`hw.id`](/docs/attributes-registry/hardware.md) | string | An identifier for the hardware component, unique within the monitored host | `win32battery_battery_testsysa33_1` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| [`hw.type`](/docs/attributes-registry/hardware.md) | string | Type of the component [1] | `battery`; `cpu`; `disk_controller` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| [`hw.name`](/docs/attributes-registry/hardware.md) | string | An easily-recognizable name for the hardware component | `eth0` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| [`hw.parent`](/docs/attributes-registry/hardware.md) | string | Unique identifier of the parent component (typically the `hw.id` attribute of the enclosure, or disk controller) | `dellStorage_perc_0` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
**[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.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 | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `cpu` | CPU | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `disk_controller` | Disk controller | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `enclosure` | Enclosure | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `fan` | Fan | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `gpu` | GPU | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `logical_disk` | Logical disk | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `memory` | Memory | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `network` | Network | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `physical_disk` | Physical disk | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `power_supply` | Power supply | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `tape_drive` | Tape drive | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `temperature` | Temperature | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `voltage` | Voltage | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
<!-- markdownlint-restore -->
<!-- prettier-ignore-end -->
<!-- END AUTOGENERATED TEXT -->
<!-- endsemconv -->
### Metric: `hw.status`
This metric is [recommended][MetricRecommended].
<!-- semconv metric.hw.status -->
<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
<!-- see templates/registry/markdown/snippet.md.j2 -->
<!-- prettier-ignore-start -->
<!-- markdownlint-capture -->
<!-- markdownlint-disable -->
| Name | Instrument Type | Unit (UCUM) | Description | Stability |
| -------- | --------------- | ----------- | -------------- | --------- |
| `hw.status` | UpDownCounter | `1` | Operational status: `1` (true) or `0` (false) for each of the possible states [1] | ![Experimental](https://img.shields.io/badge/-experimental-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.
| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
|---|---|---|---|---|---|
| [`hw.id`](/docs/attributes-registry/hardware.md) | string | An identifier for the hardware component, unique within the monitored host | `win32battery_battery_testsysa33_1` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| [`hw.state`](/docs/attributes-registry/hardware.md) | string | The current state of the component | `ok`; `degraded`; `failed` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| [`hw.type`](/docs/attributes-registry/hardware.md) | string | Type of the component [1] | `battery`; `cpu`; `disk_controller` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| [`hw.name`](/docs/attributes-registry/hardware.md) | string | An easily-recognizable name for the hardware component | `eth0` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| [`hw.parent`](/docs/attributes-registry/hardware.md) | string | Unique identifier of the parent component (typically the `hw.id` attribute of the enclosure, or disk controller) | `dellStorage_perc_0` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
**[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 | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `failed` | Failed | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `ok` | Ok | ![Experimental](https://img.shields.io/badge/-experimental-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 | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `cpu` | CPU | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `disk_controller` | Disk controller | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `enclosure` | Enclosure | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `fan` | Fan | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `gpu` | GPU | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `logical_disk` | Logical disk | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `memory` | Memory | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `network` | Network | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `physical_disk` | Physical disk | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `power_supply` | Power supply | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `tape_drive` | Tape drive | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `temperature` | Temperature | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `voltage` | Voltage | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
<!-- markdownlint-restore -->
<!-- prettier-ignore-end -->
<!-- END AUTOGENERATED TEXT -->
<!-- endsemconv -->
[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status
[MetricRecommended]: /docs/general/metric-requirement-level.md#recommended
Reference in New Issue View Git Blame Copy Permalink