diff --git a/.chloggen/hw_battery.yaml b/.chloggen/hw_battery.yaml new file mode 100755 index 0000000000..19cda7b2b3 --- /dev/null +++ b/.chloggen/hw_battery.yaml @@ -0,0 +1,22 @@ +# Use this changelog template to create an entry for release notes. +# +# If your change doesn't affect end users you should instead start +# your pull request title with [chore] or use the "Skip Changelog" label. + +# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix' +change_type: enhancement + +# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db) +component: hardware + +# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). +note: Move text hardware metrics to the hardware components, yaml and md files + +# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists. +# The values here must be integers. +issues: [2380] + +# (Optional) One or more lines of additional information to render under the primary note. +# These lines will be padded with 2 spaces and then inserted directly into the document. +# Use pipe (|) for multiline entries. +subtext: diff --git a/.github/workflows/reusable-link-check.yml b/.github/workflows/reusable-link-check.yml index e3aa6b85ab..b75f53ec86 100644 --- a/.github/workflows/reusable-link-check.yml +++ b/.github/workflows/reusable-link-check.yml @@ -26,7 +26,8 @@ jobs: run: | merge_base=$(git merge-base origin/${{ github.base_ref }} HEAD) # Using lychee's default extension filter here to match when it runs against all files - modified_files=$(git diff --name-only $merge_base...${{ github.event.pull_request.head.sha }} \ + # --diff-filter=d excludes deleted files + modified_files=$(git diff --name-only --diff-filter=d $merge_base...${{ github.event.pull_request.head.sha }} \ | grep -E '\.(md|mkd|mdx|mdown|mdwn|mkdn|mkdown|markdown|html|htm|txt)$' \ | tr '\n' ' ' || true) echo "files=$modified_files" >> $GITHUB_OUTPUT diff --git a/docs/general/metrics.md b/docs/general/metrics.md index a097a2fbf2..6bed74c022 100644 --- a/docs/general/metrics.md +++ b/docs/general/metrics.md @@ -30,7 +30,7 @@ The following semantic conventions surrounding metrics are defined: * **System metrics** * [System](/docs/system/system-metrics.md): For standard system metrics. * [Container](/docs/system/container-metrics.md) - * [Hardware](/docs/system/hardware-metrics.md): For hardware-related metrics. + * [Hardware](/docs/hardware/README.md): For hardware-related metrics. * [K8s](/docs/system/k8s-metrics.md): For K8s metrics. * [Process](/docs/system/process-metrics.md): For standard process metrics. * [Runtime Environment](/docs/runtime/README.md#metrics): For runtime environment metrics. diff --git a/docs/hardware/README.md b/docs/hardware/README.md index a183aeda18..b99bbb4a9d 100644 --- a/docs/hardware/README.md +++ b/docs/hardware/README.md @@ -14,5 +14,19 @@ Semantic conventions for hardware are defined as following: * [Common Hardware Metrics](common.md): Semantic Conventions for *common* hardware metrics. * [Physical Host Metrics](host.md): Semantic Conventions for *physical host* metrics. +* [Battery Metrics](battery.md): Semantic Conventions for *battery* metrics. +* [CPU Metrics](cpu.md): Semantic Conventions for *CPU* metrics. +* [Disk Controller Metrics](disk-controller.md): Semantic Conventions for *disk controller* metrics. +* [Enclosure Metrics](enclosure.md): Semantic Conventions for *enclosure* metrics. +* [Fan Metrics](fan.md): Semantic Conventions for *fan* metrics. +* [GPU Metrics](gpu.md): Semantic Conventions for *GPU* metrics. +* [Logical Disk Metrics](logical-disk.md): Semantic Conventions for *logical disk* metrics. +* [Memory Metrics](memory.md): Semantic Conventions for *memory* metrics. +* [Network Metrics](network.md): Semantic Conventions for *network* metrics. +* [Physical Disk Metrics](physical-disk.md): Semantic Conventions for *physical disk* metrics. +* [Power Supply Metrics](power-supply.md): Semantic Conventions for *power supply* metrics. +* [Tape Drive Metrics](tape-drive.md): Semantic Conventions for *tape drive* metrics. +* [Temperature Metrics](temperature.md): Semantic Conventions for *temperature* metrics. +* [Voltage Metrics](voltage.md): Semantic Conventions for *voltage* metrics. [DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status diff --git a/docs/hardware/battery.md b/docs/hardware/battery.md new file mode 100644 index 0000000000..78354e8ac0 --- /dev/null +++ b/docs/hardware/battery.md @@ -0,0 +1,261 @@ + + +# Semantic conventions for battery metrics + +**Status**: [Development][DocumentStatus] + + + +- [Battery metrics `hw.battery.*`](#battery-metrics-hwbattery) + - [Metric: `hw.battery.charge`](#metric-hwbatterycharge) + - [Metric: `hw.battery.charge.limit`](#metric-hwbatterychargelimit) + - [Metric: `hw.battery.time_left`](#metric-hwbatterytime_left) + - [Metric: `hw.status` (Battery)](#metric-hwstatus-battery) + + + +## 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: + + + + + + + + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`hw.id`](/docs/registry/attributes/hardware.md) | string | An identifier for the hardware component, unique within the monitored host | `win32battery_battery_testsysa33_1` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.battery.capacity`](/docs/registry/attributes/hardware.md) | string | Design capacity in Watts-hours or Amper-hours | `9.3Ah`; `50Wh` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.battery.chemistry`](/docs/registry/attributes/hardware.md) | 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` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.model`](/docs/registry/attributes/hardware.md) | string | Descriptive model name of the hardware component | `PERC H740P`; `Intel(R) Core(TM) i7-10700K`; `Dell XPS 15 Battery` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.name`](/docs/registry/attributes/hardware.md) | string | An easily-recognizable name for the hardware component | `eth0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.parent`](/docs/registry/attributes/hardware.md) | string | Unique identifier of the parent component (typically the `hw.id` attribute of the enclosure, or disk controller) | `dellStorage_perc_0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.vendor`](/docs/registry/attributes/hardware.md) | string | Vendor name of the hardware component | `Dell`; `HP`; `Intel`; `AMD`; `LSI`; `Lenovo` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | + + + + + + +### 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) | | + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`hw.id`](/docs/registry/attributes/hardware.md) | string | An identifier for the hardware component, unique within the monitored host | `win32battery_battery_testsysa33_1` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.battery.capacity`](/docs/registry/attributes/hardware.md) | string | Design capacity in Watts-hours or Amper-hours | `9.3Ah`; `50Wh` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.battery.chemistry`](/docs/registry/attributes/hardware.md) | 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` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.model`](/docs/registry/attributes/hardware.md) | string | Descriptive model name of the hardware component | `PERC H740P`; `Intel(R) Core(TM) i7-10700K`; `Dell XPS 15 Battery` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.name`](/docs/registry/attributes/hardware.md) | string | An easily-recognizable name for the hardware component | `eth0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.parent`](/docs/registry/attributes/hardware.md) | string | Unique identifier of the parent component (typically the `hw.id` attribute of the enclosure, or disk controller) | `dellStorage_perc_0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.vendor`](/docs/registry/attributes/hardware.md) | string | Vendor name of the hardware component | `Dell`; `HP`; `Intel`; `AMD`; `LSI`; `Lenovo` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | + + + + + + +### 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) | | + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`hw.id`](/docs/registry/attributes/hardware.md) | string | An identifier for the hardware component, unique within the monitored host | `win32battery_battery_testsysa33_1` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.battery.capacity`](/docs/registry/attributes/hardware.md) | string | Design capacity in Watts-hours or Amper-hours | `9.3Ah`; `50Wh` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.battery.chemistry`](/docs/registry/attributes/hardware.md) | 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` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.limit_type`](/docs/registry/attributes/hardware.md) | 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` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.model`](/docs/registry/attributes/hardware.md) | string | Descriptive model name of the hardware component | `PERC H740P`; `Intel(R) Core(TM) i7-10700K`; `Dell XPS 15 Battery` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.name`](/docs/registry/attributes/hardware.md) | string | An easily-recognizable name for the hardware component | `eth0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.parent`](/docs/registry/attributes/hardware.md) | string | Unique identifier of the parent component (typically the `hw.id` attribute of the enclosure, or disk controller) | `dellStorage_perc_0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.vendor`](/docs/registry/attributes/hardware.md) | string | Vendor name of the hardware component | `Dell`; `HP`; `Intel`; `AMD`; `LSI`; `Lenovo` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | + +--- + +`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) | | + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`hw.id`](/docs/registry/attributes/hardware.md) | string | An identifier for the hardware component, unique within the monitored host | `win32battery_battery_testsysa33_1` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.state`](/docs/registry/attributes/hardware.md) | string | The current state of the component | `degraded`; `failed`; `needs_cleaning` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.battery.state`](/docs/registry/attributes/hardware.md) | string | The current state of the battery [1] | `charging`; `discharging` | `Conditionally Required` If the battery is charging or discharging | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.battery.capacity`](/docs/registry/attributes/hardware.md) | string | Design capacity in Watts-hours or Amper-hours | `9.3Ah`; `50Wh` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.battery.chemistry`](/docs/registry/attributes/hardware.md) | 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` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.model`](/docs/registry/attributes/hardware.md) | string | Descriptive model name of the hardware component | `PERC H740P`; `Intel(R) Core(TM) i7-10700K`; `Dell XPS 15 Battery` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.name`](/docs/registry/attributes/hardware.md) | string | An easily-recognizable name for the hardware component | `eth0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.parent`](/docs/registry/attributes/hardware.md) | string | Unique identifier of the parent component (typically the `hw.id` attribute of the enclosure, or disk controller) | `dellStorage_perc_0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.vendor`](/docs/registry/attributes/hardware.md) | string | Vendor name of the hardware component | `Dell`; `HP`; `Intel`; `AMD`; `LSI`; `Lenovo` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | + +**[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. + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`hw.id`](/docs/registry/attributes/hardware.md) | string | An identifier for the hardware component, unique within the monitored host | `win32battery_battery_testsysa33_1` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.state`](/docs/registry/attributes/hardware.md) | string | The current state of the component | `degraded`; `failed`; `needs_cleaning` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.type`](/docs/registry/attributes/hardware.md) | string | Type of the component [1] | `battery`; `cpu`; `disk_controller` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.name`](/docs/registry/attributes/hardware.md) | string | An easily-recognizable name for the hardware component | `eth0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.parent`](/docs/registry/attributes/hardware.md) | string | Unique identifier of the parent component (typically the `hw.id` attribute of the enclosure, or disk controller) | `dellStorage_perc_0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-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 | ![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]: https://opentelemetry.io/docs/specs/otel/document-status +[MetricRecommended]: /docs/general/metric-requirement-level.md#recommended diff --git a/docs/hardware/common.md b/docs/hardware/common.md index 26c5f3563e..5adb7b3a4c 100644 --- a/docs/hardware/common.md +++ b/docs/hardware/common.md @@ -140,11 +140,14 @@ This metric is [recommended][MetricRecommended]. | [`error.type`](/docs/registry/attributes/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/registry/attributes/hardware.md) | string | An easily-recognizable name for the hardware component | `eth0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | | [`hw.parent`](/docs/registry/attributes/hardware.md) | string | Unique identifier of the parent component (typically the `hw.id` attribute of the enclosure, or disk controller) | `dellStorage_perc_0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`network.io.direction`](/docs/registry/attributes/network.md) | string | Direction of network traffic for network errors [3] | `receive`; `transmit` | `Recommended` | ![Development](https://img.shields.io/badge/-development-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. +**[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. @@ -174,6 +177,15 @@ This metric is [recommended][MetricRecommended]. | `temperature` | Temperature | ![Development](https://img.shields.io/badge/-development-blue) | | `voltage` | Voltage | ![Development](https://img.shields.io/badge/-development-blue) | +--- + +`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 | ![Development](https://img.shields.io/badge/-development-blue) | +| `transmit` | transmit | ![Development](https://img.shields.io/badge/-development-blue) | + @@ -251,7 +263,7 @@ This metric is [recommended][MetricRecommended]. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`hw.id`](/docs/registry/attributes/hardware.md) | string | An identifier for the hardware component, unique within the monitored host | `win32battery_battery_testsysa33_1` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | -| [`hw.state`](/docs/registry/attributes/hardware.md) | string | The current state of the component | `ok`; `degraded`; `failed` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.state`](/docs/registry/attributes/hardware.md) | string | The current state of the component | `degraded`; `failed`; `needs_cleaning` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | | [`hw.type`](/docs/registry/attributes/hardware.md) | string | Type of the component [1] | `battery`; `cpu`; `disk_controller` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | | [`hw.name`](/docs/registry/attributes/hardware.md) | string | An easily-recognizable name for the hardware component | `eth0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | | [`hw.parent`](/docs/registry/attributes/hardware.md) | string | Unique identifier of the parent component (typically the `hw.id` attribute of the enclosure, or disk controller) | `dellStorage_perc_0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | @@ -266,7 +278,9 @@ This metric is [recommended][MetricRecommended]. |---|---|---| | `degraded` | Degraded | ![Development](https://img.shields.io/badge/-development-blue) | | `failed` | Failed | ![Development](https://img.shields.io/badge/-development-blue) | -| `ok` | Ok | ![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) | --- diff --git a/docs/hardware/cpu.md b/docs/hardware/cpu.md new file mode 100644 index 0000000000..d8adc0dab0 --- /dev/null +++ b/docs/hardware/cpu.md @@ -0,0 +1,276 @@ + + +# Semantic conventions for CPU metrics + +**Status**: [Development][DocumentStatus] + + + +- [CPU metrics `hw.cpu.*`](#cpu-metrics-hwcpu) + - [Metric: `hw.errors` (CPU)](#metric-hwerrors-cpu) + - [Metric: `hw.cpu.speed`](#metric-hwcpuspeed) + - [Metric: `hw.cpu.speed.limit`](#metric-hwcpuspeedlimit) + - [Metric: `hw.status` (CPU)](#metric-hwstatus-cpu) + + + +## CPU metrics `hw.cpu.*` + +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. + +`hw.type` MUST be set to `"cpu"`. + +All CPU metrics may include the below attributes: + + + + + + + + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`hw.id`](/docs/registry/attributes/hardware.md) | string | An identifier for the hardware component, unique within the monitored host | `win32battery_battery_testsysa33_1` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.model`](/docs/registry/attributes/hardware.md) | string | Descriptive model name of the hardware component | `PERC H740P`; `Intel(R) Core(TM) i7-10700K`; `Dell XPS 15 Battery` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.name`](/docs/registry/attributes/hardware.md) | string | An easily-recognizable name for the hardware component | `eth0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.parent`](/docs/registry/attributes/hardware.md) | string | Unique identifier of the parent component (typically the `hw.id` attribute of the enclosure, or disk controller) | `dellStorage_perc_0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.vendor`](/docs/registry/attributes/hardware.md) | string | Vendor name of the hardware component | `Dell`; `HP`; `Intel`; `AMD`; `LSI`; `Lenovo` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | + + + + + + +### Metric: `hw.errors` (CPU) + +This metric is [recommended][MetricRecommended]. + +Total number of errors encountered and corrected by the CPU. + +When using this metric, the following attributes MUST be set: + +- `hw.type` MUST be set to `"cpu"` to indicate that the errors are from a CPU. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | +| -------- | --------------- | ----------- | -------------- | --------- | ------ | +| `hw.errors` | Counter | `{error}` | Number of errors encountered by the component | ![Development](https://img.shields.io/badge/-development-blue) | | + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`hw.id`](/docs/registry/attributes/hardware.md) | string | An identifier for the hardware component, unique within the monitored host | `win32battery_battery_testsysa33_1` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.type`](/docs/registry/attributes/hardware.md) | string | Type of the component [1] | `battery`; `cpu`; `disk_controller` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`error.type`](/docs/registry/attributes/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/registry/attributes/hardware.md) | string | An easily-recognizable name for the hardware component | `eth0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.parent`](/docs/registry/attributes/hardware.md) | string | Unique identifier of the parent component (typically the `hw.id` attribute of the enclosure, or disk controller) | `dellStorage_perc_0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`network.io.direction`](/docs/registry/attributes/network.md) | string | Direction of network traffic for network errors [3] | `receive`; `transmit` | `Recommended` | ![Development](https://img.shields.io/badge/-development-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. + +**[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. | ![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 | ![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) | + +--- + +`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 | ![Development](https://img.shields.io/badge/-development-blue) | +| `transmit` | transmit | ![Development](https://img.shields.io/badge/-development-blue) | + + + + + + +### Metric: `hw.cpu.speed` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | +| -------- | --------------- | ----------- | -------------- | --------- | ------ | +| `hw.cpu.speed` | Gauge | `Hz` | CPU current frequency | ![Development](https://img.shields.io/badge/-development-blue) | | + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`hw.id`](/docs/registry/attributes/hardware.md) | string | An identifier for the hardware component, unique within the monitored host | `win32battery_battery_testsysa33_1` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.model`](/docs/registry/attributes/hardware.md) | string | Descriptive model name of the hardware component | `PERC H740P`; `Intel(R) Core(TM) i7-10700K`; `Dell XPS 15 Battery` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.name`](/docs/registry/attributes/hardware.md) | string | An easily-recognizable name for the hardware component | `eth0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.parent`](/docs/registry/attributes/hardware.md) | string | Unique identifier of the parent component (typically the `hw.id` attribute of the enclosure, or disk controller) | `dellStorage_perc_0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.vendor`](/docs/registry/attributes/hardware.md) | string | Vendor name of the hardware component | `Dell`; `HP`; `Intel`; `AMD`; `LSI`; `Lenovo` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | + + + + + + +### Metric: `hw.cpu.speed.limit` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | +| -------- | --------------- | ----------- | -------------- | --------- | ------ | +| `hw.cpu.speed.limit` | Gauge | `Hz` | CPU maximum frequency | ![Development](https://img.shields.io/badge/-development-blue) | | + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`hw.id`](/docs/registry/attributes/hardware.md) | string | An identifier for the hardware component, unique within the monitored host | `win32battery_battery_testsysa33_1` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.limit_type`](/docs/registry/attributes/hardware.md) | string | Type of limit for hardware components | `throttled`; `max`; `turbo` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.model`](/docs/registry/attributes/hardware.md) | string | Descriptive model name of the hardware component | `PERC H740P`; `Intel(R) Core(TM) i7-10700K`; `Dell XPS 15 Battery` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.name`](/docs/registry/attributes/hardware.md) | string | An easily-recognizable name for the hardware component | `eth0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.parent`](/docs/registry/attributes/hardware.md) | string | Unique identifier of the parent component (typically the `hw.id` attribute of the enclosure, or disk controller) | `dellStorage_perc_0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.vendor`](/docs/registry/attributes/hardware.md) | string | Vendor name of the hardware component | `Dell`; `HP`; `Intel`; `AMD`; `LSI`; `Lenovo` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | + +--- + +`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.status` (CPU) + +This metric is [recommended][MetricRecommended]. + +Operational status: `1` (true) or `0` (false) for each of the possible states. + +When using this metric for CPU status, the following attributes MUST be set: + +- `hw.type` MUST be set to `"cpu"` to indicate that the status is for a CPU. +- `hw.state` MUST be set to one of the following values to indicate the CPU state: + - `"ok"`: The CPU is operating normally. + - `"degraded"`: The CPU is operating with reduced functionality or performance. + - `"failed"`: The CPU has failed and is not operational. + - `"predicted_failure"`: The CPU is currently operational but is predicted to fail soon. + + + + + + + + +| 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. + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`hw.id`](/docs/registry/attributes/hardware.md) | string | An identifier for the hardware component, unique within the monitored host | `win32battery_battery_testsysa33_1` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.state`](/docs/registry/attributes/hardware.md) | string | The current state of the component | `degraded`; `failed`; `needs_cleaning` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.type`](/docs/registry/attributes/hardware.md) | string | Type of the component [1] | `battery`; `cpu`; `disk_controller` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.name`](/docs/registry/attributes/hardware.md) | string | An easily-recognizable name for the hardware component | `eth0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.parent`](/docs/registry/attributes/hardware.md) | string | Unique identifier of the parent component (typically the `hw.id` attribute of the enclosure, or disk controller) | `dellStorage_perc_0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-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 | ![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]: https://opentelemetry.io/docs/specs/otel/document-status +[MetricRecommended]: /docs/general/metrics.md#metric-requirement-levels diff --git a/docs/hardware/disk-controller.md b/docs/hardware/disk-controller.md new file mode 100644 index 0000000000..b960106c84 --- /dev/null +++ b/docs/hardware/disk-controller.md @@ -0,0 +1,124 @@ + + +# Semantic conventions for disk controller metrics + +**Status**: [Development][DocumentStatus] + + + +- [Disk controller metrics `hw.disk_controller.*`](#disk-controller-metrics-hwdisk_controller) + - [Metric: `hw.status` (Disk Controller)](#metric-hwstatus-disk-controller) + + + +## Disk controller metrics `hw.disk_controller.*` + +Controller that controls the physical disks and organize them in RAID sets and logical disks that are exposed to the operating system. + +`hw.type` MUST be set to `"disk_controller"`. + +All disk controller metrics may include the below attributes: + + + + + + + + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`hw.id`](/docs/registry/attributes/hardware.md) | string | An identifier for the hardware component, unique within the monitored host | `win32battery_battery_testsysa33_1` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.bios_version`](/docs/registry/attributes/hardware.md) | string | BIOS version of the hardware component | `1.2.3` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.driver_version`](/docs/registry/attributes/hardware.md) | string | Driver version for the hardware component | `10.2.1-3` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.firmware_version`](/docs/registry/attributes/hardware.md) | string | Firmware version of the hardware component | `2.0.1` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.model`](/docs/registry/attributes/hardware.md) | string | Descriptive model name of the hardware component | `PERC H740P`; `Intel(R) Core(TM) i7-10700K`; `Dell XPS 15 Battery` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.name`](/docs/registry/attributes/hardware.md) | string | An easily-recognizable name for the hardware component | `eth0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.parent`](/docs/registry/attributes/hardware.md) | string | Unique identifier of the parent component (typically the `hw.id` attribute of the enclosure, or disk controller) | `dellStorage_perc_0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.serial_number`](/docs/registry/attributes/hardware.md) | string | Serial number of the hardware component | `CNFCP0123456789` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.vendor`](/docs/registry/attributes/hardware.md) | string | Vendor name of the hardware component | `Dell`; `HP`; `Intel`; `AMD`; `LSI`; `Lenovo` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | + + + + + + +### Metric: `hw.status` (Disk Controller) + +This metric is [recommended][MetricRecommended]. + +Operational status: `1` (true) or `0` (false) for each of the possible states. + +When using this metric for disk controller status, the following attributes MUST be set: + +- `hw.type` MUST be set to `"disk_controller"` to indicate that the status is for a disk controller. +- `hw.state` MUST be set to one of the following values to indicate the disk controller state: + - `"ok"`: The disk controller is operating normally. + - `"degraded"`: The disk controller is operating with reduced functionality or performance. + - `"failed"`: The disk controller 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] | ![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. + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`hw.id`](/docs/registry/attributes/hardware.md) | string | An identifier for the hardware component, unique within the monitored host | `win32battery_battery_testsysa33_1` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.state`](/docs/registry/attributes/hardware.md) | string | The current state of the component | `degraded`; `failed`; `needs_cleaning` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.type`](/docs/registry/attributes/hardware.md) | string | Type of the component [1] | `battery`; `cpu`; `disk_controller` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.name`](/docs/registry/attributes/hardware.md) | string | An easily-recognizable name for the hardware component | `eth0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.parent`](/docs/registry/attributes/hardware.md) | string | Unique identifier of the parent component (typically the `hw.id` attribute of the enclosure, or disk controller) | `dellStorage_perc_0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-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 | ![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]: https://opentelemetry.io/docs/specs/otel/document-status +[MetricRecommended]: /docs/general/metrics.md#metric-requirement-levels diff --git a/docs/hardware/enclosure.md b/docs/hardware/enclosure.md new file mode 100644 index 0000000000..3a689c4f8e --- /dev/null +++ b/docs/hardware/enclosure.md @@ -0,0 +1,124 @@ + + +# Semantic conventions for enclosure metrics + +**Status**: [Development][DocumentStatus] + + + +- [Enclosure metrics `hw.enclosure.*`](#enclosure-metrics-hwenclosure) + - [Metric: `hw.status` (Enclosure)](#metric-hwstatus-enclosure) + + + +## Enclosure metrics `hw.enclosure.*` + +Computer chassis (can be an expansion enclosure). + +`hw.type` MUST be set to `"enclosure"`. + +All enclosure metrics may include the below attributes: + + + + + + + + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`hw.id`](/docs/registry/attributes/hardware.md) | string | An identifier for the hardware component, unique within the monitored host | `win32battery_battery_testsysa33_1` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.bios_version`](/docs/registry/attributes/hardware.md) | string | BIOS version of the hardware component | `1.2.3` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.enclosure.type`](/docs/registry/attributes/hardware.md) | string | Type of the enclosure (useful for modular systems) | `Computer`; `Storage`; `Switch` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.model`](/docs/registry/attributes/hardware.md) | string | Descriptive model name of the hardware component | `PERC H740P`; `Intel(R) Core(TM) i7-10700K`; `Dell XPS 15 Battery` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.name`](/docs/registry/attributes/hardware.md) | string | An easily-recognizable name for the hardware component | `eth0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.parent`](/docs/registry/attributes/hardware.md) | string | Unique identifier of the parent component (typically the `hw.id` attribute of the enclosure, or disk controller) | `dellStorage_perc_0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.serial_number`](/docs/registry/attributes/hardware.md) | string | Serial number of the hardware component | `CNFCP0123456789` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.vendor`](/docs/registry/attributes/hardware.md) | string | Vendor name of the hardware component | `Dell`; `HP`; `Intel`; `AMD`; `LSI`; `Lenovo` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | + + + + + + +### Metric: `hw.status` (Enclosure) + +This metric is [recommended][MetricRecommended]. + +Operational status: `1` (true) or `0` (false) for each of the possible states. + +When using this metric for enclosure status, the following attributes MUST be set: + +- `hw.type` MUST be set to `"enclosure"` to indicate that the status is for an enclosure. +- `hw.state` MUST be set to one of the following values to indicate the enclosure state: + - `"ok"`: The enclosure is operating normally. + - `"degraded"`: The enclosure is operating with reduced functionality or performance. + - `"failed"`: The enclosure has failed and is not operational. + - `"open"`: The enclosure is open. + + + + + + + + +| 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. + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`hw.id`](/docs/registry/attributes/hardware.md) | string | An identifier for the hardware component, unique within the monitored host | `win32battery_battery_testsysa33_1` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.state`](/docs/registry/attributes/hardware.md) | string | The current state of the component | `degraded`; `failed`; `needs_cleaning` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.type`](/docs/registry/attributes/hardware.md) | string | Type of the component [1] | `battery`; `cpu`; `disk_controller` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.name`](/docs/registry/attributes/hardware.md) | string | An easily-recognizable name for the hardware component | `eth0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.parent`](/docs/registry/attributes/hardware.md) | string | Unique identifier of the parent component (typically the `hw.id` attribute of the enclosure, or disk controller) | `dellStorage_perc_0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-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 | ![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]: https://opentelemetry.io/docs/specs/otel/document-status +[MetricRecommended]: /docs/general/metrics.md#metric-requirement-levels diff --git a/docs/hardware/fan.md b/docs/hardware/fan.md new file mode 100644 index 0000000000..987f61a039 --- /dev/null +++ b/docs/hardware/fan.md @@ -0,0 +1,220 @@ + + +# Semantic conventions for fan metrics + +**Status**: [Development][DocumentStatus] + + + +- [Fan metrics `hw.fan.*`](#fan-metrics-hwfan) + - [Metric: `hw.fan.speed`](#metric-hwfanspeed) + - [Metric: `hw.fan.speed.limit`](#metric-hwfanspeedlimit) + - [Metric: `hw.fan.speed_ratio`](#metric-hwfanspeed_ratio) + - [Metric: `hw.status` (Fan)](#metric-hwstatus-fan) + + + +## Fan metrics `hw.fan.*` + +Fan that keeps the air flowing to maintain the internal temperature of a computer. + +`hw.type` MUST be set to `"fan"`. + +All fan metrics may include the below attributes: + + + + + + + + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`hw.id`](/docs/registry/attributes/hardware.md) | string | An identifier for the hardware component, unique within the monitored host | `win32battery_battery_testsysa33_1` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.name`](/docs/registry/attributes/hardware.md) | string | An easily-recognizable name for the hardware component | `eth0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.parent`](/docs/registry/attributes/hardware.md) | string | Unique identifier of the parent component (typically the `hw.id` attribute of the enclosure, or disk controller) | `dellStorage_perc_0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.sensor_location`](/docs/registry/attributes/hardware.md) | string | Location of the sensor | `cpu0`; `ps1`; `INLET`; `CPU0_DIE`; `AMBIENT`; `MOTHERBOARD`; `PS0 V3_3`; `MAIN_12V`; `CPU_VCORE` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | + + + + + + +### Metric: `hw.fan.speed` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | +| -------- | --------------- | ----------- | -------------- | --------- | ------ | +| `hw.fan.speed` | Gauge | `rpm` | Fan speed in revolutions per minute | ![Development](https://img.shields.io/badge/-development-blue) | | + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`hw.id`](/docs/registry/attributes/hardware.md) | string | An identifier for the hardware component, unique within the monitored host | `win32battery_battery_testsysa33_1` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.name`](/docs/registry/attributes/hardware.md) | string | An easily-recognizable name for the hardware component | `eth0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.parent`](/docs/registry/attributes/hardware.md) | string | Unique identifier of the parent component (typically the `hw.id` attribute of the enclosure, or disk controller) | `dellStorage_perc_0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.sensor_location`](/docs/registry/attributes/hardware.md) | string | Location of the sensor | `cpu0`; `ps1`; `INLET`; `CPU0_DIE`; `AMBIENT`; `MOTHERBOARD`; `PS0 V3_3`; `MAIN_12V`; `CPU_VCORE` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | + + + + + + +### Metric: `hw.fan.speed.limit` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | +| -------- | --------------- | ----------- | -------------- | --------- | ------ | +| `hw.fan.speed.limit` | Gauge | `rpm` | Speed limit in rpm | ![Development](https://img.shields.io/badge/-development-blue) | | + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`hw.id`](/docs/registry/attributes/hardware.md) | string | An identifier for the hardware component, unique within the monitored host | `win32battery_battery_testsysa33_1` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.limit_type`](/docs/registry/attributes/hardware.md) | string | Type of limit for hardware components | `low.critical`; `low.degraded`; `max` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.name`](/docs/registry/attributes/hardware.md) | string | An easily-recognizable name for the hardware component | `eth0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.parent`](/docs/registry/attributes/hardware.md) | string | Unique identifier of the parent component (typically the `hw.id` attribute of the enclosure, or disk controller) | `dellStorage_perc_0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.sensor_location`](/docs/registry/attributes/hardware.md) | string | Location of the sensor | `cpu0`; `ps1`; `INLET`; `CPU0_DIE`; `AMBIENT`; `MOTHERBOARD`; `PS0 V3_3`; `MAIN_12V`; `CPU_VCORE` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | + +--- + +`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.fan.speed_ratio` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | +| -------- | --------------- | ----------- | -------------- | --------- | ------ | +| `hw.fan.speed_ratio` | Gauge | `1` | Fan speed expressed as a fraction of its maximum speed | ![Development](https://img.shields.io/badge/-development-blue) | | + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`hw.id`](/docs/registry/attributes/hardware.md) | string | An identifier for the hardware component, unique within the monitored host | `win32battery_battery_testsysa33_1` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.name`](/docs/registry/attributes/hardware.md) | string | An easily-recognizable name for the hardware component | `eth0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.parent`](/docs/registry/attributes/hardware.md) | string | Unique identifier of the parent component (typically the `hw.id` attribute of the enclosure, or disk controller) | `dellStorage_perc_0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.sensor_location`](/docs/registry/attributes/hardware.md) | string | Location of the sensor | `cpu0`; `ps1`; `INLET`; `CPU0_DIE`; `AMBIENT`; `MOTHERBOARD`; `PS0 V3_3`; `MAIN_12V`; `CPU_VCORE` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | + + + + + + +### Metric: `hw.status` (Fan) + +This metric is [recommended][MetricRecommended]. + +Operational status: `1` (true) or `0` (false) for each of the possible states. + +When using this metric for fan status, the following attributes MUST be set: + +- `hw.type` MUST be set to `"fan"` to indicate that the status is for a fan. +- `hw.state` MUST be set to one of the following values to indicate the fan state: + - `"ok"`: The fan is operating normally. + - `"degraded"`: The fan is operating with reduced functionality or performance. + - `"failed"`: The fan 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] | ![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. + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`hw.id`](/docs/registry/attributes/hardware.md) | string | An identifier for the hardware component, unique within the monitored host | `win32battery_battery_testsysa33_1` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.state`](/docs/registry/attributes/hardware.md) | string | The current state of the component | `degraded`; `failed`; `needs_cleaning` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.type`](/docs/registry/attributes/hardware.md) | string | Type of the component [1] | `battery`; `cpu`; `disk_controller` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.name`](/docs/registry/attributes/hardware.md) | string | An easily-recognizable name for the hardware component | `eth0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.parent`](/docs/registry/attributes/hardware.md) | string | Unique identifier of the parent component (typically the `hw.id` attribute of the enclosure, or disk controller) | `dellStorage_perc_0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-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 | ![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]: https://opentelemetry.io/docs/specs/otel/document-status +[MetricRecommended]: /docs/general/metrics.md#metric-requirement-levels diff --git a/docs/hardware/gpu.md b/docs/hardware/gpu.md new file mode 100644 index 0000000000..6b73a22a75 --- /dev/null +++ b/docs/hardware/gpu.md @@ -0,0 +1,388 @@ + + +# Semantic conventions for GPU metrics + +**Status**: [Development][DocumentStatus] + + + +- [GPU metrics `hw.gpu.*`](#gpu-metrics-hwgpu) + - [Metric: `hw.errors` (GPU)](#metric-hwerrors-gpu) + - [Metric: `hw.gpu.io`](#metric-hwgpuio) + - [Metric: `hw.gpu.memory.limit`](#metric-hwgpumemorylimit) + - [Metric: `hw.gpu.memory.utilization`](#metric-hwgpumemoryutilization) + - [Metric: `hw.gpu.memory.usage`](#metric-hwgpumemoryusage) + - [Metric: `hw.gpu.utilization`](#metric-hwgpuutilization) + - [Metric: `hw.status` (GPU)](#metric-hwstatus-gpu) + + + +## GPU metrics `hw.gpu.*` + +Graphics Processing Unit (discrete). + +`hw.type` MUST be set to `"gpu"`. + +All GPU metrics may include the below attributes: + + + + + + + + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`hw.id`](/docs/registry/attributes/hardware.md) | string | An identifier for the hardware component, unique within the monitored host | `win32battery_battery_testsysa33_1` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.driver_version`](/docs/registry/attributes/hardware.md) | string | Driver version for the hardware component | `10.2.1-3` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.firmware_version`](/docs/registry/attributes/hardware.md) | string | Firmware version of the hardware component | `2.0.1` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.model`](/docs/registry/attributes/hardware.md) | string | Descriptive model name of the hardware component | `PERC H740P`; `Intel(R) Core(TM) i7-10700K`; `Dell XPS 15 Battery` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.name`](/docs/registry/attributes/hardware.md) | string | An easily-recognizable name for the hardware component | `eth0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.parent`](/docs/registry/attributes/hardware.md) | string | Unique identifier of the parent component (typically the `hw.id` attribute of the enclosure, or disk controller) | `dellStorage_perc_0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.serial_number`](/docs/registry/attributes/hardware.md) | string | Serial number of the hardware component | `CNFCP0123456789` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.vendor`](/docs/registry/attributes/hardware.md) | string | Vendor name of the hardware component | `Dell`; `HP`; `Intel`; `AMD`; `LSI`; `Lenovo` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | + + + + + + +### Metric: `hw.errors` (GPU) + +This metric is [recommended][MetricRecommended]. + +Number of errors encountered by the GPU. + +When using this metric, the following attributes MUST be set: + +- `hw.type` MUST be set to `"gpu"` to indicate that the errors are from a GPU. +- `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. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | +| -------- | --------------- | ----------- | -------------- | --------- | ------ | +| `hw.errors` | Counter | `{error}` | Number of errors encountered by the component | ![Development](https://img.shields.io/badge/-development-blue) | | + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`hw.id`](/docs/registry/attributes/hardware.md) | string | An identifier for the hardware component, unique within the monitored host | `win32battery_battery_testsysa33_1` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.type`](/docs/registry/attributes/hardware.md) | string | Type of the component [1] | `battery`; `cpu`; `disk_controller` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`error.type`](/docs/registry/attributes/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/registry/attributes/hardware.md) | string | An easily-recognizable name for the hardware component | `eth0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.parent`](/docs/registry/attributes/hardware.md) | string | Unique identifier of the parent component (typically the `hw.id` attribute of the enclosure, or disk controller) | `dellStorage_perc_0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`network.io.direction`](/docs/registry/attributes/network.md) | string | Direction of network traffic for network errors [3] | `receive`; `transmit` | `Recommended` | ![Development](https://img.shields.io/badge/-development-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. + +**[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. | ![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 | ![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) | + +--- + +`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 | ![Development](https://img.shields.io/badge/-development-blue) | +| `transmit` | transmit | ![Development](https://img.shields.io/badge/-development-blue) | + + + + + + +### Metric: `hw.gpu.io` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | +| -------- | --------------- | ----------- | -------------- | --------- | ------ | +| `hw.gpu.io` | Counter | `By` | Received and transmitted bytes by the GPU | ![Development](https://img.shields.io/badge/-development-blue) | | + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`hw.id`](/docs/registry/attributes/hardware.md) | string | An identifier for the hardware component, unique within the monitored host | `win32battery_battery_testsysa33_1` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`network.io.direction`](/docs/registry/attributes/network.md) | string | The network IO operation direction. | `receive`; `transmit` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.driver_version`](/docs/registry/attributes/hardware.md) | string | Driver version for the hardware component | `10.2.1-3` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.firmware_version`](/docs/registry/attributes/hardware.md) | string | Firmware version of the hardware component | `2.0.1` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.model`](/docs/registry/attributes/hardware.md) | string | Descriptive model name of the hardware component | `PERC H740P`; `Intel(R) Core(TM) i7-10700K`; `Dell XPS 15 Battery` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.name`](/docs/registry/attributes/hardware.md) | string | An easily-recognizable name for the hardware component | `eth0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.parent`](/docs/registry/attributes/hardware.md) | string | Unique identifier of the parent component (typically the `hw.id` attribute of the enclosure, or disk controller) | `dellStorage_perc_0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.serial_number`](/docs/registry/attributes/hardware.md) | string | Serial number of the hardware component | `CNFCP0123456789` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.vendor`](/docs/registry/attributes/hardware.md) | string | Vendor name of the hardware component | `Dell`; `HP`; `Intel`; `AMD`; `LSI`; `Lenovo` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | + +--- + +`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 | ![Development](https://img.shields.io/badge/-development-blue) | +| `transmit` | transmit | ![Development](https://img.shields.io/badge/-development-blue) | + + + + + + +### Metric: `hw.gpu.memory.limit` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | +| -------- | --------------- | ----------- | -------------- | --------- | ------ | +| `hw.gpu.memory.limit` | UpDownCounter | `By` | Size of the GPU memory | ![Development](https://img.shields.io/badge/-development-blue) | | + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`hw.id`](/docs/registry/attributes/hardware.md) | string | An identifier for the hardware component, unique within the monitored host | `win32battery_battery_testsysa33_1` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.driver_version`](/docs/registry/attributes/hardware.md) | string | Driver version for the hardware component | `10.2.1-3` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.firmware_version`](/docs/registry/attributes/hardware.md) | string | Firmware version of the hardware component | `2.0.1` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.model`](/docs/registry/attributes/hardware.md) | string | Descriptive model name of the hardware component | `PERC H740P`; `Intel(R) Core(TM) i7-10700K`; `Dell XPS 15 Battery` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.name`](/docs/registry/attributes/hardware.md) | string | An easily-recognizable name for the hardware component | `eth0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.parent`](/docs/registry/attributes/hardware.md) | string | Unique identifier of the parent component (typically the `hw.id` attribute of the enclosure, or disk controller) | `dellStorage_perc_0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.serial_number`](/docs/registry/attributes/hardware.md) | string | Serial number of the hardware component | `CNFCP0123456789` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.vendor`](/docs/registry/attributes/hardware.md) | string | Vendor name of the hardware component | `Dell`; `HP`; `Intel`; `AMD`; `LSI`; `Lenovo` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | + + + + + + +### Metric: `hw.gpu.memory.utilization` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | +| -------- | --------------- | ----------- | -------------- | --------- | ------ | +| `hw.gpu.memory.utilization` | Gauge | `1` | Fraction of GPU memory used | ![Development](https://img.shields.io/badge/-development-blue) | | + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`hw.id`](/docs/registry/attributes/hardware.md) | string | An identifier for the hardware component, unique within the monitored host | `win32battery_battery_testsysa33_1` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.driver_version`](/docs/registry/attributes/hardware.md) | string | Driver version for the hardware component | `10.2.1-3` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.firmware_version`](/docs/registry/attributes/hardware.md) | string | Firmware version of the hardware component | `2.0.1` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.model`](/docs/registry/attributes/hardware.md) | string | Descriptive model name of the hardware component | `PERC H740P`; `Intel(R) Core(TM) i7-10700K`; `Dell XPS 15 Battery` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.name`](/docs/registry/attributes/hardware.md) | string | An easily-recognizable name for the hardware component | `eth0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.parent`](/docs/registry/attributes/hardware.md) | string | Unique identifier of the parent component (typically the `hw.id` attribute of the enclosure, or disk controller) | `dellStorage_perc_0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.serial_number`](/docs/registry/attributes/hardware.md) | string | Serial number of the hardware component | `CNFCP0123456789` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.vendor`](/docs/registry/attributes/hardware.md) | string | Vendor name of the hardware component | `Dell`; `HP`; `Intel`; `AMD`; `LSI`; `Lenovo` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | + + + + + + +### Metric: `hw.gpu.memory.usage` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | +| -------- | --------------- | ----------- | -------------- | --------- | ------ | +| `hw.gpu.memory.usage` | UpDownCounter | `By` | GPU memory used | ![Development](https://img.shields.io/badge/-development-blue) | | + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`hw.id`](/docs/registry/attributes/hardware.md) | string | An identifier for the hardware component, unique within the monitored host | `win32battery_battery_testsysa33_1` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.driver_version`](/docs/registry/attributes/hardware.md) | string | Driver version for the hardware component | `10.2.1-3` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.firmware_version`](/docs/registry/attributes/hardware.md) | string | Firmware version of the hardware component | `2.0.1` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.model`](/docs/registry/attributes/hardware.md) | string | Descriptive model name of the hardware component | `PERC H740P`; `Intel(R) Core(TM) i7-10700K`; `Dell XPS 15 Battery` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.name`](/docs/registry/attributes/hardware.md) | string | An easily-recognizable name for the hardware component | `eth0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.parent`](/docs/registry/attributes/hardware.md) | string | Unique identifier of the parent component (typically the `hw.id` attribute of the enclosure, or disk controller) | `dellStorage_perc_0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.serial_number`](/docs/registry/attributes/hardware.md) | string | Serial number of the hardware component | `CNFCP0123456789` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.vendor`](/docs/registry/attributes/hardware.md) | string | Vendor name of the hardware component | `Dell`; `HP`; `Intel`; `AMD`; `LSI`; `Lenovo` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | + + + + + + +### Metric: `hw.gpu.utilization` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | +| -------- | --------------- | ----------- | -------------- | --------- | ------ | +| `hw.gpu.utilization` | Gauge | `1` | Fraction of time spent in a specific task | ![Development](https://img.shields.io/badge/-development-blue) | | + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`hw.id`](/docs/registry/attributes/hardware.md) | string | An identifier for the hardware component, unique within the monitored host | `win32battery_battery_testsysa33_1` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.driver_version`](/docs/registry/attributes/hardware.md) | string | Driver version for the hardware component | `10.2.1-3` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.firmware_version`](/docs/registry/attributes/hardware.md) | string | Firmware version of the hardware component | `2.0.1` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.gpu.task`](/docs/registry/attributes/hardware.md) | string | Type of task the GPU is performing | `decoder`; `encoder`; `general` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.model`](/docs/registry/attributes/hardware.md) | string | Descriptive model name of the hardware component | `PERC H740P`; `Intel(R) Core(TM) i7-10700K`; `Dell XPS 15 Battery` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.name`](/docs/registry/attributes/hardware.md) | string | An easily-recognizable name for the hardware component | `eth0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.parent`](/docs/registry/attributes/hardware.md) | string | Unique identifier of the parent component (typically the `hw.id` attribute of the enclosure, or disk controller) | `dellStorage_perc_0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.serial_number`](/docs/registry/attributes/hardware.md) | string | Serial number of the hardware component | `CNFCP0123456789` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.vendor`](/docs/registry/attributes/hardware.md) | string | Vendor name of the hardware component | `Dell`; `HP`; `Intel`; `AMD`; `LSI`; `Lenovo` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | + +--- + +`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 | ![Development](https://img.shields.io/badge/-development-blue) | +| `encoder` | Encoder | ![Development](https://img.shields.io/badge/-development-blue) | +| `general` | General | ![Development](https://img.shields.io/badge/-development-blue) | + + + + + + +### Metric: `hw.status` (GPU) + +This metric is [recommended][MetricRecommended]. + +Operational status: `1` (true) or `0` (false) for each of the possible states. + +When using this metric for GPU status, the following attributes MUST be set: + +- `hw.type` MUST be set to `"gpu"` to indicate that the status is for a GPU. +- `hw.state` MUST be set to one of the following values to indicate the GPU state: + - `"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. + + + + + + + + +| 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. + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`hw.id`](/docs/registry/attributes/hardware.md) | string | An identifier for the hardware component, unique within the monitored host | `win32battery_battery_testsysa33_1` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.state`](/docs/registry/attributes/hardware.md) | string | The current state of the component | `degraded`; `failed`; `needs_cleaning` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.type`](/docs/registry/attributes/hardware.md) | string | Type of the component [1] | `battery`; `cpu`; `disk_controller` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.name`](/docs/registry/attributes/hardware.md) | string | An easily-recognizable name for the hardware component | `eth0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.parent`](/docs/registry/attributes/hardware.md) | string | Unique identifier of the parent component (typically the `hw.id` attribute of the enclosure, or disk controller) | `dellStorage_perc_0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-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 | ![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]: https://opentelemetry.io/docs/specs/otel/document-status +[MetricRecommended]: /docs/general/metrics.md#metric-requirement-levels diff --git a/docs/hardware/logical-disk.md b/docs/hardware/logical-disk.md new file mode 100644 index 0000000000..4067642be2 --- /dev/null +++ b/docs/hardware/logical-disk.md @@ -0,0 +1,321 @@ + + +# Semantic conventions for logical disk metrics + +**Status**: [Development][DocumentStatus] + + + +- [Logical disk metrics `hw.logical_disk.*`](#logical-disk-metrics-hwlogical_disk) + - [Metric: `hw.errors` (Logical Disk)](#metric-hwerrors-logical-disk) + - [Metric: `hw.logical_disk.limit`](#metric-hwlogical_disklimit) + - [Metric: `hw.logical_disk.usage`](#metric-hwlogical_diskusage) + - [Metric: `hw.logical_disk.utilization`](#metric-hwlogical_diskutilization) + - [Metric: `hw.status` (Logical Disk)](#metric-hwstatus-logical-disk) + + + +## Logical disk metrics `hw.logical_disk.*` + +Storage extent presented as a physical disk by a disk controller to the operating system (e.g. a RAID 1 set made of 2 disks, and exposed as /dev/hdd0 by the controller). + +`hw.type` MUST be set to `"logical_disk"`. + +All logical disk metrics may include the below attributes: + + + + + + + + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`hw.id`](/docs/registry/attributes/hardware.md) | string | An identifier for the hardware component, unique within the monitored host | `win32battery_battery_testsysa33_1` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.logical_disk.raid_level`](/docs/registry/attributes/hardware.md) | string | RAID Level of the logical disk | `RAID0+1`; `RAID5`; `RAID10` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.name`](/docs/registry/attributes/hardware.md) | string | An easily-recognizable name for the hardware component | `eth0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.parent`](/docs/registry/attributes/hardware.md) | string | Unique identifier of the parent component (typically the `hw.id` attribute of the enclosure, or disk controller) | `dellStorage_perc_0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | + + + + + + +### Metric: `hw.errors` (Logical Disk) + +This metric is [recommended][MetricRecommended]. + +Number of errors encountered on this logical disk. + +When using this metric, the following attributes MUST be set: + +- `hw.type` MUST be set to `"logical_disk"` to indicate that the errors are from a logical disk. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | +| -------- | --------------- | ----------- | -------------- | --------- | ------ | +| `hw.errors` | Counter | `{error}` | Number of errors encountered by the component | ![Development](https://img.shields.io/badge/-development-blue) | | + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`hw.id`](/docs/registry/attributes/hardware.md) | string | An identifier for the hardware component, unique within the monitored host | `win32battery_battery_testsysa33_1` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.type`](/docs/registry/attributes/hardware.md) | string | Type of the component [1] | `battery`; `cpu`; `disk_controller` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`error.type`](/docs/registry/attributes/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/registry/attributes/hardware.md) | string | An easily-recognizable name for the hardware component | `eth0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.parent`](/docs/registry/attributes/hardware.md) | string | Unique identifier of the parent component (typically the `hw.id` attribute of the enclosure, or disk controller) | `dellStorage_perc_0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`network.io.direction`](/docs/registry/attributes/network.md) | string | Direction of network traffic for network errors [3] | `receive`; `transmit` | `Recommended` | ![Development](https://img.shields.io/badge/-development-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. + +**[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. | ![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 | ![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) | + +--- + +`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 | ![Development](https://img.shields.io/badge/-development-blue) | +| `transmit` | transmit | ![Development](https://img.shields.io/badge/-development-blue) | + + + + + + +### Metric: `hw.logical_disk.limit` + +This metric is [recommended][MetricRecommended]. + +Size of the logical disk. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | +| -------- | --------------- | ----------- | -------------- | --------- | ------ | +| `hw.logical_disk.limit` | UpDownCounter | `By` | Size of the logical disk | ![Development](https://img.shields.io/badge/-development-blue) | | + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`hw.id`](/docs/registry/attributes/hardware.md) | string | An identifier for the hardware component, unique within the monitored host | `win32battery_battery_testsysa33_1` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.logical_disk.raid_level`](/docs/registry/attributes/hardware.md) | string | RAID Level of the logical disk | `RAID0+1`; `RAID5`; `RAID10` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.name`](/docs/registry/attributes/hardware.md) | string | An easily-recognizable name for the hardware component | `eth0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.parent`](/docs/registry/attributes/hardware.md) | string | Unique identifier of the parent component (typically the `hw.id` attribute of the enclosure, or disk controller) | `dellStorage_perc_0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | + + + + + + +### Metric: `hw.logical_disk.usage` + +This metric is [recommended][MetricRecommended]. + +Logical disk space usage. + +When using this metric, the following attributes MUST be set: + +- `hw.logical_disk.state` MUST be set to one of the following values: + - `"used"`: The amount of disk space that is in use. + - `"free"`: The amount of disk space that is free. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | +| -------- | --------------- | ----------- | -------------- | --------- | ------ | +| `hw.logical_disk.usage` | UpDownCounter | `By` | Logical disk space usage | ![Development](https://img.shields.io/badge/-development-blue) | | + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`hw.id`](/docs/registry/attributes/hardware.md) | string | An identifier for the hardware component, unique within the monitored host | `win32battery_battery_testsysa33_1` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.logical_disk.state`](/docs/registry/attributes/hardware.md) | string | State of the logical disk space usage | `used`; `free` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.logical_disk.raid_level`](/docs/registry/attributes/hardware.md) | string | RAID Level of the logical disk | `RAID0+1`; `RAID5`; `RAID10` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.name`](/docs/registry/attributes/hardware.md) | string | An easily-recognizable name for the hardware component | `eth0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.parent`](/docs/registry/attributes/hardware.md) | string | Unique identifier of the parent component (typically the `hw.id` attribute of the enclosure, or disk controller) | `dellStorage_perc_0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | + +--- + +`hw.logical_disk.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 | +|---|---|---| +| `free` | Free | ![Development](https://img.shields.io/badge/-development-blue) | +| `used` | Used | ![Development](https://img.shields.io/badge/-development-blue) | + + + + + + +### Metric: `hw.logical_disk.utilization` + +This metric is [recommended][MetricRecommended]. + +Logical disk space utilization as a fraction. + +When using this metric, the following attributes MUST be set: + +- `hw.logical_disk.state` MUST be set to one of the following values: + - `"used"`: The fraction of disk space that is in use. + - `"free"`: The fraction of disk space that is free. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | +| -------- | --------------- | ----------- | -------------- | --------- | ------ | +| `hw.logical_disk.utilization` | Gauge | `1` | Logical disk space utilization as a fraction | ![Development](https://img.shields.io/badge/-development-blue) | | + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`hw.id`](/docs/registry/attributes/hardware.md) | string | An identifier for the hardware component, unique within the monitored host | `win32battery_battery_testsysa33_1` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.logical_disk.state`](/docs/registry/attributes/hardware.md) | string | State of the logical disk space usage | `used`; `free` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.logical_disk.raid_level`](/docs/registry/attributes/hardware.md) | string | RAID Level of the logical disk | `RAID0+1`; `RAID5`; `RAID10` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.name`](/docs/registry/attributes/hardware.md) | string | An easily-recognizable name for the hardware component | `eth0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.parent`](/docs/registry/attributes/hardware.md) | string | Unique identifier of the parent component (typically the `hw.id` attribute of the enclosure, or disk controller) | `dellStorage_perc_0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | + +--- + +`hw.logical_disk.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 | +|---|---|---| +| `free` | Free | ![Development](https://img.shields.io/badge/-development-blue) | +| `used` | Used | ![Development](https://img.shields.io/badge/-development-blue) | + + + + + + +### Metric: `hw.status` (Logical Disk) + +This metric is [recommended][MetricRecommended]. + +Operational status: `1` (true) or `0` (false) for each of the possible states. + +When using this metric for logical disk status, the following attributes MUST be set: + +- `hw.type` MUST be set to `"logical_disk"` to indicate that the status is for a logical disk. +- `hw.state` MUST be set to one of the following values to indicate the logical disk state: + - `"ok"`: The logical disk is operating normally. + - `"degraded"`: The logical disk is operating with reduced functionality or performance. + - `"failed"`: The logical disk 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] | ![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. + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`hw.id`](/docs/registry/attributes/hardware.md) | string | An identifier for the hardware component, unique within the monitored host | `win32battery_battery_testsysa33_1` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.state`](/docs/registry/attributes/hardware.md) | string | The current state of the component | `degraded`; `failed`; `needs_cleaning` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.type`](/docs/registry/attributes/hardware.md) | string | Type of the component [1] | `battery`; `cpu`; `disk_controller` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.name`](/docs/registry/attributes/hardware.md) | string | An easily-recognizable name for the hardware component | `eth0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.parent`](/docs/registry/attributes/hardware.md) | string | Unique identifier of the parent component (typically the `hw.id` attribute of the enclosure, or disk controller) | `dellStorage_perc_0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-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 | ![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]: https://opentelemetry.io/docs/specs/otel/document-status +[MetricRecommended]: /docs/general/metrics.md#metric-requirement-levels diff --git a/docs/hardware/memory.md b/docs/hardware/memory.md new file mode 100644 index 0000000000..2362b389bf --- /dev/null +++ b/docs/hardware/memory.md @@ -0,0 +1,236 @@ + + +# Semantic conventions for memory metrics + +**Status**: [Development][DocumentStatus] + + + +- [Memory metrics `hw.memory.*`](#memory-metrics-hwmemory) + - [Metric: `hw.errors` (Memory)](#metric-hwerrors-memory) + - [Metric: `hw.memory.size`](#metric-hwmemorysize) + - [Metric: `hw.status` (Memory)](#metric-hwstatus-memory) + + + +## Memory metrics `hw.memory.*` + +A memory module in a computer system. + +`hw.type` MUST be set to `"memory"`. + +All memory metrics may include the below attributes: + + + + + + + + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`hw.id`](/docs/registry/attributes/hardware.md) | string | An identifier for the hardware component, unique within the monitored host | `win32battery_battery_testsysa33_1` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.memory.type`](/docs/registry/attributes/hardware.md) | string | Type of the memory module | `DDR4`; `DDR5`; `LPDDR5` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.model`](/docs/registry/attributes/hardware.md) | string | Descriptive model name of the hardware component | `PERC H740P`; `Intel(R) Core(TM) i7-10700K`; `Dell XPS 15 Battery` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.name`](/docs/registry/attributes/hardware.md) | string | An easily-recognizable name for the hardware component | `eth0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.parent`](/docs/registry/attributes/hardware.md) | string | Unique identifier of the parent component (typically the `hw.id` attribute of the enclosure, or disk controller) | `dellStorage_perc_0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.serial_number`](/docs/registry/attributes/hardware.md) | string | Serial number of the hardware component | `CNFCP0123456789` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.vendor`](/docs/registry/attributes/hardware.md) | string | Vendor name of the hardware component | `Dell`; `HP`; `Intel`; `AMD`; `LSI`; `Lenovo` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | + + + + + + +### Metric: `hw.errors` (Memory) + +This metric is [recommended][MetricRecommended]. + +Number of errors encountered on this memory module. + +When using this metric, the following attributes MUST be set: + +- `hw.type` MUST be set to `"memory"` to indicate that the errors are from a memory module. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | +| -------- | --------------- | ----------- | -------------- | --------- | ------ | +| `hw.errors` | Counter | `{error}` | Number of errors encountered by the component | ![Development](https://img.shields.io/badge/-development-blue) | | + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`hw.id`](/docs/registry/attributes/hardware.md) | string | An identifier for the hardware component, unique within the monitored host | `win32battery_battery_testsysa33_1` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.type`](/docs/registry/attributes/hardware.md) | string | Type of the component [1] | `battery`; `cpu`; `disk_controller` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`error.type`](/docs/registry/attributes/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/registry/attributes/hardware.md) | string | An easily-recognizable name for the hardware component | `eth0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.parent`](/docs/registry/attributes/hardware.md) | string | Unique identifier of the parent component (typically the `hw.id` attribute of the enclosure, or disk controller) | `dellStorage_perc_0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`network.io.direction`](/docs/registry/attributes/network.md) | string | Direction of network traffic for network errors [3] | `receive`; `transmit` | `Recommended` | ![Development](https://img.shields.io/badge/-development-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. + +**[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. | ![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 | ![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) | + +--- + +`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 | ![Development](https://img.shields.io/badge/-development-blue) | +| `transmit` | transmit | ![Development](https://img.shields.io/badge/-development-blue) | + + + + + + +### Metric: `hw.memory.size` + +This metric is [recommended][MetricRecommended]. + +Size of the memory module. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | +| -------- | --------------- | ----------- | -------------- | --------- | ------ | +| `hw.memory.size` | UpDownCounter | `By` | Size of the memory module | ![Development](https://img.shields.io/badge/-development-blue) | | + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`hw.id`](/docs/registry/attributes/hardware.md) | string | An identifier for the hardware component, unique within the monitored host | `win32battery_battery_testsysa33_1` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.memory.type`](/docs/registry/attributes/hardware.md) | string | Type of the memory module | `DDR4`; `DDR5`; `LPDDR5` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.model`](/docs/registry/attributes/hardware.md) | string | Descriptive model name of the hardware component | `PERC H740P`; `Intel(R) Core(TM) i7-10700K`; `Dell XPS 15 Battery` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.name`](/docs/registry/attributes/hardware.md) | string | An easily-recognizable name for the hardware component | `eth0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.parent`](/docs/registry/attributes/hardware.md) | string | Unique identifier of the parent component (typically the `hw.id` attribute of the enclosure, or disk controller) | `dellStorage_perc_0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.serial_number`](/docs/registry/attributes/hardware.md) | string | Serial number of the hardware component | `CNFCP0123456789` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.vendor`](/docs/registry/attributes/hardware.md) | string | Vendor name of the hardware component | `Dell`; `HP`; `Intel`; `AMD`; `LSI`; `Lenovo` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | + + + + + + +### Metric: `hw.status` (Memory) + +This metric is [recommended][MetricRecommended]. + +Operational status: `1` (true) or `0` (false) for each of the possible states. + +When using this metric for memory status, the following attributes MUST be set: + +- `hw.type` MUST be set to `"memory"` to indicate that the status is for a memory module. +- `hw.state` MUST be set to one of the following values to indicate the memory state: + - `"ok"`: The memory module is operating normally. + - `"degraded"`: The memory module is operating with reduced functionality or performance. + - `"failed"`: The memory module has failed and is not operational. + - `"predicted_failure"`: The memory module is currently operational but is predicted to fail soon. + + + + + + + + +| 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. + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`hw.id`](/docs/registry/attributes/hardware.md) | string | An identifier for the hardware component, unique within the monitored host | `win32battery_battery_testsysa33_1` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.state`](/docs/registry/attributes/hardware.md) | string | The current state of the component | `degraded`; `failed`; `needs_cleaning` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.type`](/docs/registry/attributes/hardware.md) | string | Type of the component [1] | `battery`; `cpu`; `disk_controller` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.name`](/docs/registry/attributes/hardware.md) | string | An easily-recognizable name for the hardware component | `eth0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.parent`](/docs/registry/attributes/hardware.md) | string | Unique identifier of the parent component (typically the `hw.id` attribute of the enclosure, or disk controller) | `dellStorage_perc_0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-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 | ![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]: https://opentelemetry.io/docs/specs/otel/document-status +[MetricRecommended]: /docs/general/metrics.md#metric-requirement-levels diff --git a/docs/hardware/network.md b/docs/hardware/network.md new file mode 100644 index 0000000000..c1f9296626 --- /dev/null +++ b/docs/hardware/network.md @@ -0,0 +1,410 @@ + + +# Semantic conventions for network metrics + +**Status**: [Development][DocumentStatus] + + + +- [Network metrics `hw.network.*`](#network-metrics-hwnetwork) + - [Metric: `hw.errors` (Network)](#metric-hwerrors-network) + - [Metric: `hw.network.bandwidth.limit`](#metric-hwnetworkbandwidthlimit) + - [Metric: `hw.network.bandwidth.utilization`](#metric-hwnetworkbandwidthutilization) + - [Metric: `hw.network.io`](#metric-hwnetworkio) + - [Metric: `hw.network.packets`](#metric-hwnetworkpackets) + - [Metric: `hw.network.up`](#metric-hwnetworkup) + - [Metric: `hw.status` (Network)](#metric-hwstatus-network) + + + +## 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: + + + + + + + + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`hw.id`](/docs/registry/attributes/hardware.md) | string | An identifier for the hardware component, unique within the monitored host | `win32battery_battery_testsysa33_1` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.model`](/docs/registry/attributes/hardware.md) | string | Descriptive model name of the hardware component | `PERC H740P`; `Intel(R) Core(TM) i7-10700K`; `Dell XPS 15 Battery` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.name`](/docs/registry/attributes/hardware.md) | string | An easily-recognizable name for the hardware component | `eth0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.network.logical_addresses`](/docs/registry/attributes/hardware.md) | string[] | Logical addresses of the adapter (e.g. IP address, or WWPN) | `["172.16.8.21", "57.11.193.42"]` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.network.physical_address`](/docs/registry/attributes/hardware.md) | string | Physical address of the adapter (e.g. MAC address, or WWNN) | `00-90-F5-E9-7B-36` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.parent`](/docs/registry/attributes/hardware.md) | string | Unique identifier of the parent component (typically the `hw.id` attribute of the enclosure, or disk controller) | `dellStorage_perc_0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.serial_number`](/docs/registry/attributes/hardware.md) | string | Serial number of the hardware component | `CNFCP0123456789` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.vendor`](/docs/registry/attributes/hardware.md) | string | Vendor name of the hardware component | `Dell`; `HP`; `Intel`; `AMD`; `LSI`; `Lenovo` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | + + + + + + +### Metric: `hw.errors` (Network) + +This metric is [recommended][MetricRecommended]. + +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 | ![Development](https://img.shields.io/badge/-development-blue) | | + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`hw.id`](/docs/registry/attributes/hardware.md) | string | An identifier for the hardware component, unique within the monitored host | `win32battery_battery_testsysa33_1` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.type`](/docs/registry/attributes/hardware.md) | string | Type of the component [1] | `battery`; `cpu`; `disk_controller` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`error.type`](/docs/registry/attributes/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/registry/attributes/hardware.md) | string | An easily-recognizable name for the hardware component | `eth0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.parent`](/docs/registry/attributes/hardware.md) | string | Unique identifier of the parent component (typically the `hw.id` attribute of the enclosure, or disk controller) | `dellStorage_perc_0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`network.io.direction`](/docs/registry/attributes/network.md) | string | Direction of network traffic for network errors [3] | `receive`; `transmit` | `Recommended` | ![Development](https://img.shields.io/badge/-development-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. + +**[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. | ![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 | ![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) | + +--- + +`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 | ![Development](https://img.shields.io/badge/-development-blue) | +| `transmit` | transmit | ![Development](https://img.shields.io/badge/-development-blue) | + + + + + + +### Metric: `hw.network.bandwidth.limit` + +This metric is [recommended][MetricRecommended]. + +Link speed. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | +| -------- | --------------- | ----------- | -------------- | --------- | ------ | +| `hw.network.bandwidth.limit` | UpDownCounter | `By/s` | Link speed | ![Development](https://img.shields.io/badge/-development-blue) | | + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`hw.id`](/docs/registry/attributes/hardware.md) | string | An identifier for the hardware component, unique within the monitored host | `win32battery_battery_testsysa33_1` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.model`](/docs/registry/attributes/hardware.md) | string | Descriptive model name of the hardware component | `PERC H740P`; `Intel(R) Core(TM) i7-10700K`; `Dell XPS 15 Battery` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.name`](/docs/registry/attributes/hardware.md) | string | An easily-recognizable name for the hardware component | `eth0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.network.logical_addresses`](/docs/registry/attributes/hardware.md) | string[] | Logical addresses of the adapter (e.g. IP address, or WWPN) | `["172.16.8.21", "57.11.193.42"]` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.network.physical_address`](/docs/registry/attributes/hardware.md) | string | Physical address of the adapter (e.g. MAC address, or WWNN) | `00-90-F5-E9-7B-36` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.parent`](/docs/registry/attributes/hardware.md) | string | Unique identifier of the parent component (typically the `hw.id` attribute of the enclosure, or disk controller) | `dellStorage_perc_0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.serial_number`](/docs/registry/attributes/hardware.md) | string | Serial number of the hardware component | `CNFCP0123456789` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.vendor`](/docs/registry/attributes/hardware.md) | string | Vendor name of the hardware component | `Dell`; `HP`; `Intel`; `AMD`; `LSI`; `Lenovo` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | + + + + + + +### Metric: `hw.network.bandwidth.utilization` + +This metric is [recommended][MetricRecommended]. + +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 | ![Development](https://img.shields.io/badge/-development-blue) | | + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`hw.id`](/docs/registry/attributes/hardware.md) | string | An identifier for the hardware component, unique within the monitored host | `win32battery_battery_testsysa33_1` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.model`](/docs/registry/attributes/hardware.md) | string | Descriptive model name of the hardware component | `PERC H740P`; `Intel(R) Core(TM) i7-10700K`; `Dell XPS 15 Battery` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.name`](/docs/registry/attributes/hardware.md) | string | An easily-recognizable name for the hardware component | `eth0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.network.logical_addresses`](/docs/registry/attributes/hardware.md) | string[] | Logical addresses of the adapter (e.g. IP address, or WWPN) | `["172.16.8.21", "57.11.193.42"]` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.network.physical_address`](/docs/registry/attributes/hardware.md) | string | Physical address of the adapter (e.g. MAC address, or WWNN) | `00-90-F5-E9-7B-36` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.parent`](/docs/registry/attributes/hardware.md) | string | Unique identifier of the parent component (typically the `hw.id` attribute of the enclosure, or disk controller) | `dellStorage_perc_0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.serial_number`](/docs/registry/attributes/hardware.md) | string | Serial number of the hardware component | `CNFCP0123456789` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.vendor`](/docs/registry/attributes/hardware.md) | string | Vendor name of the hardware component | `Dell`; `HP`; `Intel`; `AMD`; `LSI`; `Lenovo` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | + + + + + + +### Metric: `hw.network.io` + +This metric is [recommended][MetricRecommended]. + +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 | ![Development](https://img.shields.io/badge/-development-blue) | | + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`hw.id`](/docs/registry/attributes/hardware.md) | string | An identifier for the hardware component, unique within the monitored host | `win32battery_battery_testsysa33_1` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`network.io.direction`](/docs/registry/attributes/network.md) | string | The network IO operation direction. | `receive`; `transmit` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.model`](/docs/registry/attributes/hardware.md) | string | Descriptive model name of the hardware component | `PERC H740P`; `Intel(R) Core(TM) i7-10700K`; `Dell XPS 15 Battery` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.name`](/docs/registry/attributes/hardware.md) | string | An easily-recognizable name for the hardware component | `eth0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.network.logical_addresses`](/docs/registry/attributes/hardware.md) | string[] | Logical addresses of the adapter (e.g. IP address, or WWPN) | `["172.16.8.21", "57.11.193.42"]` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.network.physical_address`](/docs/registry/attributes/hardware.md) | string | Physical address of the adapter (e.g. MAC address, or WWNN) | `00-90-F5-E9-7B-36` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.parent`](/docs/registry/attributes/hardware.md) | string | Unique identifier of the parent component (typically the `hw.id` attribute of the enclosure, or disk controller) | `dellStorage_perc_0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.serial_number`](/docs/registry/attributes/hardware.md) | string | Serial number of the hardware component | `CNFCP0123456789` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.vendor`](/docs/registry/attributes/hardware.md) | string | Vendor name of the hardware component | `Dell`; `HP`; `Intel`; `AMD`; `LSI`; `Lenovo` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | + +--- + +`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 | ![Development](https://img.shields.io/badge/-development-blue) | +| `transmit` | transmit | ![Development](https://img.shields.io/badge/-development-blue) | + + + + + + +### Metric: `hw.network.packets` + +This metric is [recommended][MetricRecommended]. + +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) | ![Development](https://img.shields.io/badge/-development-blue) | | + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`hw.id`](/docs/registry/attributes/hardware.md) | string | An identifier for the hardware component, unique within the monitored host | `win32battery_battery_testsysa33_1` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`network.io.direction`](/docs/registry/attributes/network.md) | string | The network IO operation direction. | `receive`; `transmit` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.model`](/docs/registry/attributes/hardware.md) | string | Descriptive model name of the hardware component | `PERC H740P`; `Intel(R) Core(TM) i7-10700K`; `Dell XPS 15 Battery` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.name`](/docs/registry/attributes/hardware.md) | string | An easily-recognizable name for the hardware component | `eth0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.network.logical_addresses`](/docs/registry/attributes/hardware.md) | string[] | Logical addresses of the adapter (e.g. IP address, or WWPN) | `["172.16.8.21", "57.11.193.42"]` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.network.physical_address`](/docs/registry/attributes/hardware.md) | string | Physical address of the adapter (e.g. MAC address, or WWNN) | `00-90-F5-E9-7B-36` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.parent`](/docs/registry/attributes/hardware.md) | string | Unique identifier of the parent component (typically the `hw.id` attribute of the enclosure, or disk controller) | `dellStorage_perc_0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.serial_number`](/docs/registry/attributes/hardware.md) | string | Serial number of the hardware component | `CNFCP0123456789` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.vendor`](/docs/registry/attributes/hardware.md) | string | Vendor name of the hardware component | `Dell`; `HP`; `Intel`; `AMD`; `LSI`; `Lenovo` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | + +--- + +`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 | ![Development](https://img.shields.io/badge/-development-blue) | +| `transmit` | transmit | ![Development](https://img.shields.io/badge/-development-blue) | + + + + + + +### Metric: `hw.network.up` + +This metric is [recommended][MetricRecommended]. + +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) | ![Development](https://img.shields.io/badge/-development-blue) | | + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`hw.id`](/docs/registry/attributes/hardware.md) | string | An identifier for the hardware component, unique within the monitored host | `win32battery_battery_testsysa33_1` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.model`](/docs/registry/attributes/hardware.md) | string | Descriptive model name of the hardware component | `PERC H740P`; `Intel(R) Core(TM) i7-10700K`; `Dell XPS 15 Battery` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.name`](/docs/registry/attributes/hardware.md) | string | An easily-recognizable name for the hardware component | `eth0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.network.logical_addresses`](/docs/registry/attributes/hardware.md) | string[] | Logical addresses of the adapter (e.g. IP address, or WWPN) | `["172.16.8.21", "57.11.193.42"]` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.network.physical_address`](/docs/registry/attributes/hardware.md) | string | Physical address of the adapter (e.g. MAC address, or WWNN) | `00-90-F5-E9-7B-36` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.parent`](/docs/registry/attributes/hardware.md) | string | Unique identifier of the parent component (typically the `hw.id` attribute of the enclosure, or disk controller) | `dellStorage_perc_0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.serial_number`](/docs/registry/attributes/hardware.md) | string | Serial number of the hardware component | `CNFCP0123456789` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.vendor`](/docs/registry/attributes/hardware.md) | string | Vendor name of the hardware component | `Dell`; `HP`; `Intel`; `AMD`; `LSI`; `Lenovo` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | + + + + + + +### Metric: `hw.status` (Network) + +This metric is [recommended][MetricRecommended]. + +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] | ![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. + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`hw.id`](/docs/registry/attributes/hardware.md) | string | An identifier for the hardware component, unique within the monitored host | `win32battery_battery_testsysa33_1` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.state`](/docs/registry/attributes/hardware.md) | string | The current state of the component | `degraded`; `failed`; `needs_cleaning` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.type`](/docs/registry/attributes/hardware.md) | string | Type of the component [1] | `battery`; `cpu`; `disk_controller` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.name`](/docs/registry/attributes/hardware.md) | string | An easily-recognizable name for the hardware component | `eth0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.parent`](/docs/registry/attributes/hardware.md) | string | Unique identifier of the parent component (typically the `hw.id` attribute of the enclosure, or disk controller) | `dellStorage_perc_0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-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 | ![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]: https://opentelemetry.io/docs/specs/otel/document-status +[MetricRecommended]: /docs/general/metrics.md#metric-requirement-levels diff --git a/docs/hardware/physical-disk.md b/docs/hardware/physical-disk.md new file mode 100644 index 0000000000..7a23f4993f --- /dev/null +++ b/docs/hardware/physical-disk.md @@ -0,0 +1,328 @@ + + +# Semantic conventions for physical disk metrics + +**Status**: [Development][DocumentStatus] + + + +- [Physical disk metrics `hw.physical_disk.*`](#physical-disk-metrics-hwphysical_disk) + - [Metric: `hw.errors` (Physical Disk)](#metric-hwerrors-physical-disk) + - [Metric: `hw.physical_disk.endurance_utilization`](#metric-hwphysical_diskendurance_utilization) + - [Metric: `hw.physical_disk.size`](#metric-hwphysical_disksize) + - [Metric: `hw.physical_disk.smart`](#metric-hwphysical_disksmart) + - [Metric: `hw.status` (Physical Disk)](#metric-hwstatus-physical-disk) + + + +## Physical disk metrics `hw.physical_disk.*` + +Physical hard drive (HDD or SDD). + +`hw.type` MUST be set to `"physical_disk"`. + +All physical disk metrics may include the below attributes: + + + + + + + + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`hw.id`](/docs/registry/attributes/hardware.md) | string | An identifier for the hardware component, unique within the monitored host | `win32battery_battery_testsysa33_1` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.firmware_version`](/docs/registry/attributes/hardware.md) | string | Firmware version of the hardware component | `2.0.1` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.model`](/docs/registry/attributes/hardware.md) | string | Descriptive model name of the hardware component | `PERC H740P`; `Intel(R) Core(TM) i7-10700K`; `Dell XPS 15 Battery` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.name`](/docs/registry/attributes/hardware.md) | string | An easily-recognizable name for the hardware component | `eth0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.parent`](/docs/registry/attributes/hardware.md) | string | Unique identifier of the parent component (typically the `hw.id` attribute of the enclosure, or disk controller) | `dellStorage_perc_0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.physical_disk.type`](/docs/registry/attributes/hardware.md) | string | Type of the physical disk | `HDD`; `SSD`; `10K` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.serial_number`](/docs/registry/attributes/hardware.md) | string | Serial number of the hardware component | `CNFCP0123456789` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.vendor`](/docs/registry/attributes/hardware.md) | string | Vendor name of the hardware component | `Dell`; `HP`; `Intel`; `AMD`; `LSI`; `Lenovo` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | + + + + + + +### Metric: `hw.errors` (Physical Disk) + +This metric is [recommended][MetricRecommended]. + +Number of errors encountered on this disk. + +When using this metric, the following attributes MUST be set: + +- `hw.type` MUST be set to `"physical_disk"` to indicate that the errors are from a physical disk. + +The following attributes SHOULD be set: + +- `error.type` SHOULD be set to indicate the type of error, such as `"bad_sector"`, `"write"`, etc. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | +| -------- | --------------- | ----------- | -------------- | --------- | ------ | +| `hw.errors` | Counter | `{error}` | Number of errors encountered by the component | ![Development](https://img.shields.io/badge/-development-blue) | | + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`hw.id`](/docs/registry/attributes/hardware.md) | string | An identifier for the hardware component, unique within the monitored host | `win32battery_battery_testsysa33_1` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.type`](/docs/registry/attributes/hardware.md) | string | Type of the component [1] | `battery`; `cpu`; `disk_controller` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`error.type`](/docs/registry/attributes/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/registry/attributes/hardware.md) | string | An easily-recognizable name for the hardware component | `eth0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.parent`](/docs/registry/attributes/hardware.md) | string | Unique identifier of the parent component (typically the `hw.id` attribute of the enclosure, or disk controller) | `dellStorage_perc_0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`network.io.direction`](/docs/registry/attributes/network.md) | string | Direction of network traffic for network errors [3] | `receive`; `transmit` | `Recommended` | ![Development](https://img.shields.io/badge/-development-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. + +**[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. | ![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 | ![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) | + +--- + +`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 | ![Development](https://img.shields.io/badge/-development-blue) | +| `transmit` | transmit | ![Development](https://img.shields.io/badge/-development-blue) | + + + + + + +### Metric: `hw.physical_disk.endurance_utilization` + +This metric is [recommended][MetricRecommended]. + +Endurance remaining for this SSD disk. + +When using this metric, the following attributes MUST be set: + +- `hw.physical_disk.state` MUST be set to `"remaining"` to indicate the remaining endurance. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | +| -------- | --------------- | ----------- | -------------- | --------- | ------ | +| `hw.physical_disk.endurance_utilization` | Gauge | `1` | Endurance remaining for this SSD disk | ![Development](https://img.shields.io/badge/-development-blue) | | + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`hw.id`](/docs/registry/attributes/hardware.md) | string | An identifier for the hardware component, unique within the monitored host | `win32battery_battery_testsysa33_1` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.physical_disk.state`](/docs/registry/attributes/hardware.md) | string | State of the physical disk endurance utilization | `remaining` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.firmware_version`](/docs/registry/attributes/hardware.md) | string | Firmware version of the hardware component | `2.0.1` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.model`](/docs/registry/attributes/hardware.md) | string | Descriptive model name of the hardware component | `PERC H740P`; `Intel(R) Core(TM) i7-10700K`; `Dell XPS 15 Battery` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.name`](/docs/registry/attributes/hardware.md) | string | An easily-recognizable name for the hardware component | `eth0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.parent`](/docs/registry/attributes/hardware.md) | string | Unique identifier of the parent component (typically the `hw.id` attribute of the enclosure, or disk controller) | `dellStorage_perc_0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.physical_disk.type`](/docs/registry/attributes/hardware.md) | string | Type of the physical disk | `HDD`; `SSD`; `10K` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.serial_number`](/docs/registry/attributes/hardware.md) | string | Serial number of the hardware component | `CNFCP0123456789` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.vendor`](/docs/registry/attributes/hardware.md) | string | Vendor name of the hardware component | `Dell`; `HP`; `Intel`; `AMD`; `LSI`; `Lenovo` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | + +--- + +`hw.physical_disk.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 | +|---|---|---| +| `remaining` | Remaining | ![Development](https://img.shields.io/badge/-development-blue) | + + + + + + +### Metric: `hw.physical_disk.size` + +This metric is [recommended][MetricRecommended]. + +Size of the disk. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | +| -------- | --------------- | ----------- | -------------- | --------- | ------ | +| `hw.physical_disk.size` | UpDownCounter | `By` | Size of the disk | ![Development](https://img.shields.io/badge/-development-blue) | | + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`hw.id`](/docs/registry/attributes/hardware.md) | string | An identifier for the hardware component, unique within the monitored host | `win32battery_battery_testsysa33_1` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.firmware_version`](/docs/registry/attributes/hardware.md) | string | Firmware version of the hardware component | `2.0.1` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.model`](/docs/registry/attributes/hardware.md) | string | Descriptive model name of the hardware component | `PERC H740P`; `Intel(R) Core(TM) i7-10700K`; `Dell XPS 15 Battery` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.name`](/docs/registry/attributes/hardware.md) | string | An easily-recognizable name for the hardware component | `eth0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.parent`](/docs/registry/attributes/hardware.md) | string | Unique identifier of the parent component (typically the `hw.id` attribute of the enclosure, or disk controller) | `dellStorage_perc_0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.physical_disk.type`](/docs/registry/attributes/hardware.md) | string | Type of the physical disk | `HDD`; `SSD`; `10K` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.serial_number`](/docs/registry/attributes/hardware.md) | string | Serial number of the hardware component | `CNFCP0123456789` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.vendor`](/docs/registry/attributes/hardware.md) | string | Vendor name of the hardware component | `Dell`; `HP`; `Intel`; `AMD`; `LSI`; `Lenovo` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | + + + + + + +### Metric: `hw.physical_disk.smart` + +This metric is [recommended][MetricRecommended]. + +Value of the corresponding [S.M.A.R.T.](https://wikipedia.org/wiki/S.M.A.R.T.) attribute. + +The following attributes SHOULD be set: + +- `hw.physical_disk.smart_attribute` SHOULD be set to indicate the specific S.M.A.R.T. attribute being reported, such as `"Seek Error Rate"`, `"Spin Retry Count"`, etc. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | +| -------- | --------------- | ----------- | -------------- | --------- | ------ | +| `hw.physical_disk.smart` | Gauge | `1` | Value of the corresponding [S.M.A.R.T.](https://wikipedia.org/wiki/S.M.A.R.T.) (Self-Monitoring, Analysis, and Reporting Technology) attribute | ![Development](https://img.shields.io/badge/-development-blue) | | + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`hw.id`](/docs/registry/attributes/hardware.md) | string | An identifier for the hardware component, unique within the monitored host | `win32battery_battery_testsysa33_1` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.firmware_version`](/docs/registry/attributes/hardware.md) | string | Firmware version of the hardware component | `2.0.1` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.model`](/docs/registry/attributes/hardware.md) | string | Descriptive model name of the hardware component | `PERC H740P`; `Intel(R) Core(TM) i7-10700K`; `Dell XPS 15 Battery` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.name`](/docs/registry/attributes/hardware.md) | string | An easily-recognizable name for the hardware component | `eth0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.parent`](/docs/registry/attributes/hardware.md) | string | Unique identifier of the parent component (typically the `hw.id` attribute of the enclosure, or disk controller) | `dellStorage_perc_0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.physical_disk.smart_attribute`](/docs/registry/attributes/hardware.md) | string | [S.M.A.R.T.](https://wikipedia.org/wiki/S.M.A.R.T.) (Self-Monitoring, Analysis, and Reporting Technology) attribute of the physical disk | `Spin Retry Count`; `Seek Error Rate` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.physical_disk.type`](/docs/registry/attributes/hardware.md) | string | Type of the physical disk | `HDD`; `SSD`; `10K` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.serial_number`](/docs/registry/attributes/hardware.md) | string | Serial number of the hardware component | `CNFCP0123456789` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.vendor`](/docs/registry/attributes/hardware.md) | string | Vendor name of the hardware component | `Dell`; `HP`; `Intel`; `AMD`; `LSI`; `Lenovo` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | + + + + + + +### Metric: `hw.status` (Physical Disk) + +This metric is [recommended][MetricRecommended]. + +Operational status: `1` (true) or `0` (false) for each of the possible states. + +When using this metric for physical disk status, the following attributes MUST be set: + +- `hw.type` MUST be set to `"physical_disk"` to indicate that the status is for a physical disk. +- `hw.state` MUST be set to one of the following values to indicate the physical disk state: + - `"ok"`: The physical disk is operating normally. + - `"degraded"`: The physical disk is operating with reduced functionality or performance. + - `"failed"`: The physical disk has failed and is not operational. + - `"predicted_failure"`: The physical disk is currently operational but is predicted to fail soon. + + + + + + + + +| 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. + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`hw.id`](/docs/registry/attributes/hardware.md) | string | An identifier for the hardware component, unique within the monitored host | `win32battery_battery_testsysa33_1` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.state`](/docs/registry/attributes/hardware.md) | string | The current state of the component | `degraded`; `failed`; `needs_cleaning` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.type`](/docs/registry/attributes/hardware.md) | string | Type of the component [1] | `battery`; `cpu`; `disk_controller` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.name`](/docs/registry/attributes/hardware.md) | string | An easily-recognizable name for the hardware component | `eth0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.parent`](/docs/registry/attributes/hardware.md) | string | Unique identifier of the parent component (typically the `hw.id` attribute of the enclosure, or disk controller) | `dellStorage_perc_0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-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 | ![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]: https://opentelemetry.io/docs/specs/otel/document-status +[MetricRecommended]: /docs/general/metrics.md#metric-requirement-levels diff --git a/docs/hardware/power-supply.md b/docs/hardware/power-supply.md new file mode 100644 index 0000000000..e530f8e9af --- /dev/null +++ b/docs/hardware/power-supply.md @@ -0,0 +1,238 @@ + + +# Semantic conventions for power supply metrics + +**Status**: [Development][DocumentStatus] + + + +- [Power supply metrics `hw.power_supply.*`](#power-supply-metrics-hwpower_supply) + - [Metric: `hw.power_supply.limit`](#metric-hwpower_supplylimit) + - [Metric: `hw.power_supply.utilization`](#metric-hwpower_supplyutilization) + - [Metric: `hw.power_supply.usage`](#metric-hwpower_supplyusage) + - [Metric: `hw.status` (Power Supply)](#metric-hwstatus-power-supply) + + + +## Power supply metrics `hw.power_supply.*` + +Power supply converting AC current to DC used by the motherboard and the GPUs. + +`hw.type` MUST be set to `"power_supply"`. + +All power supply metrics may include the below attributes: + + + + + + + + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`hw.id`](/docs/registry/attributes/hardware.md) | string | An identifier for the hardware component, unique within the monitored host | `win32battery_battery_testsysa33_1` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.model`](/docs/registry/attributes/hardware.md) | string | Descriptive model name of the hardware component | `PERC H740P`; `Intel(R) Core(TM) i7-10700K`; `Dell XPS 15 Battery` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.name`](/docs/registry/attributes/hardware.md) | string | An easily-recognizable name for the hardware component | `eth0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.parent`](/docs/registry/attributes/hardware.md) | string | Unique identifier of the parent component (typically the `hw.id` attribute of the enclosure, or disk controller) | `dellStorage_perc_0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.serial_number`](/docs/registry/attributes/hardware.md) | string | Serial number of the hardware component | `CNFCP0123456789` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.vendor`](/docs/registry/attributes/hardware.md) | string | Vendor name of the hardware component | `Dell`; `HP`; `Intel`; `AMD`; `LSI`; `Lenovo` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | + + + + + + +### Metric: `hw.power_supply.limit` + +This metric is [recommended][MetricRecommended]. + +Maximum power output of the power supply. + +The following attributes SHOULD be set: + +- `hw.power_supply.limit_type` SHOULD be set to indicate the type of limit, such as `"max"`, `"critical"`, or `"throttled"`. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | +| -------- | --------------- | ----------- | -------------- | --------- | ------ | +| `hw.power_supply.limit` | UpDownCounter | `W` | Maximum power output of the power supply | ![Development](https://img.shields.io/badge/-development-blue) | | + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`hw.id`](/docs/registry/attributes/hardware.md) | string | An identifier for the hardware component, unique within the monitored host | `win32battery_battery_testsysa33_1` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.limit_type`](/docs/registry/attributes/hardware.md) | string | Type of limit for hardware components | `max`; `critical`; `throttled` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.model`](/docs/registry/attributes/hardware.md) | string | Descriptive model name of the hardware component | `PERC H740P`; `Intel(R) Core(TM) i7-10700K`; `Dell XPS 15 Battery` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.name`](/docs/registry/attributes/hardware.md) | string | An easily-recognizable name for the hardware component | `eth0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.parent`](/docs/registry/attributes/hardware.md) | string | Unique identifier of the parent component (typically the `hw.id` attribute of the enclosure, or disk controller) | `dellStorage_perc_0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.serial_number`](/docs/registry/attributes/hardware.md) | string | Serial number of the hardware component | `CNFCP0123456789` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.vendor`](/docs/registry/attributes/hardware.md) | string | Vendor name of the hardware component | `Dell`; `HP`; `Intel`; `AMD`; `LSI`; `Lenovo` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | + +--- + +`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.power_supply.utilization` + +This metric is [recommended][MetricRecommended]. + +Utilization of the power supply as a fraction of its maximum output. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | +| -------- | --------------- | ----------- | -------------- | --------- | ------ | +| `hw.power_supply.utilization` | Gauge | `1` | Utilization of the power supply as a fraction of its maximum output | ![Development](https://img.shields.io/badge/-development-blue) | | + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`hw.id`](/docs/registry/attributes/hardware.md) | string | An identifier for the hardware component, unique within the monitored host | `win32battery_battery_testsysa33_1` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.model`](/docs/registry/attributes/hardware.md) | string | Descriptive model name of the hardware component | `PERC H740P`; `Intel(R) Core(TM) i7-10700K`; `Dell XPS 15 Battery` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.name`](/docs/registry/attributes/hardware.md) | string | An easily-recognizable name for the hardware component | `eth0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.parent`](/docs/registry/attributes/hardware.md) | string | Unique identifier of the parent component (typically the `hw.id` attribute of the enclosure, or disk controller) | `dellStorage_perc_0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.serial_number`](/docs/registry/attributes/hardware.md) | string | Serial number of the hardware component | `CNFCP0123456789` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.vendor`](/docs/registry/attributes/hardware.md) | string | Vendor name of the hardware component | `Dell`; `HP`; `Intel`; `AMD`; `LSI`; `Lenovo` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | + + + + + + +### Metric: `hw.power_supply.usage` + +This metric is [recommended][MetricRecommended]. + +Current power usage of the power supply. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | +| -------- | --------------- | ----------- | -------------- | --------- | ------ | +| `hw.power_supply.usage` | UpDownCounter | `W` | Current power output of the power supply | ![Development](https://img.shields.io/badge/-development-blue) | | + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`hw.id`](/docs/registry/attributes/hardware.md) | string | An identifier for the hardware component, unique within the monitored host | `win32battery_battery_testsysa33_1` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.model`](/docs/registry/attributes/hardware.md) | string | Descriptive model name of the hardware component | `PERC H740P`; `Intel(R) Core(TM) i7-10700K`; `Dell XPS 15 Battery` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.name`](/docs/registry/attributes/hardware.md) | string | An easily-recognizable name for the hardware component | `eth0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.parent`](/docs/registry/attributes/hardware.md) | string | Unique identifier of the parent component (typically the `hw.id` attribute of the enclosure, or disk controller) | `dellStorage_perc_0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.serial_number`](/docs/registry/attributes/hardware.md) | string | Serial number of the hardware component | `CNFCP0123456789` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.vendor`](/docs/registry/attributes/hardware.md) | string | Vendor name of the hardware component | `Dell`; `HP`; `Intel`; `AMD`; `LSI`; `Lenovo` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | + + + + + + +### Metric: `hw.status` (Power Supply) + +This metric is [recommended][MetricRecommended]. + +Operational status: `1` (true) or `0` (false) for each of the possible states. + +When using this metric for power supply status, the following attributes MUST be set: + +- `hw.type` MUST be set to `"power_supply"` to indicate that the status is for a power supply. +- `hw.state` MUST be set to one of the following values to indicate the power supply state: + - `"ok"`: The power supply is operating normally. + - `"degraded"`: The power supply is operating with reduced functionality or performance. + - `"failed"`: The power supply 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] | ![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. + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`hw.id`](/docs/registry/attributes/hardware.md) | string | An identifier for the hardware component, unique within the monitored host | `win32battery_battery_testsysa33_1` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.state`](/docs/registry/attributes/hardware.md) | string | The current state of the component | `degraded`; `failed`; `needs_cleaning` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.type`](/docs/registry/attributes/hardware.md) | string | Type of the component [1] | `battery`; `cpu`; `disk_controller` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.name`](/docs/registry/attributes/hardware.md) | string | An easily-recognizable name for the hardware component | `eth0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.parent`](/docs/registry/attributes/hardware.md) | string | Unique identifier of the parent component (typically the `hw.id` attribute of the enclosure, or disk controller) | `dellStorage_perc_0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-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 | ![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]: https://opentelemetry.io/docs/specs/otel/document-status +[MetricRecommended]: /docs/general/metrics.md#metric-requirement-levels diff --git a/docs/hardware/tape-drive.md b/docs/hardware/tape-drive.md new file mode 100644 index 0000000000..d4a8e2c27f --- /dev/null +++ b/docs/hardware/tape-drive.md @@ -0,0 +1,253 @@ + + +# Semantic conventions for tape drive metrics + +**Status**: [Development][DocumentStatus] + + + +- [Tape drive metrics `hw.tape_drive.*`](#tape-drive-metrics-hwtape_drive) + - [Metric: `hw.errors` (Tape Drive)](#metric-hwerrors-tape-drive) + - [Metric: `hw.tape_drive.operations`](#metric-hwtape_driveoperations) + - [Metric: `hw.status` (Tape Drive)](#metric-hwstatus-tape-drive) + + + +## Tape drive metrics `hw.tape_drive.*` + +A tape drive in a computer or in a tape library (excluding virtual tape libraries). + +`hw.type` MUST be set to `"tape_drive"`. + +All tape drive metrics may include the below attributes: + + + + + + + + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`hw.id`](/docs/registry/attributes/hardware.md) | string | An identifier for the hardware component, unique within the monitored host | `win32battery_battery_testsysa33_1` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.model`](/docs/registry/attributes/hardware.md) | string | Descriptive model name of the hardware component | `PERC H740P`; `Intel(R) Core(TM) i7-10700K`; `Dell XPS 15 Battery` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.name`](/docs/registry/attributes/hardware.md) | string | An easily-recognizable name for the hardware component | `eth0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.parent`](/docs/registry/attributes/hardware.md) | string | Unique identifier of the parent component (typically the `hw.id` attribute of the enclosure, or disk controller) | `dellStorage_perc_0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.serial_number`](/docs/registry/attributes/hardware.md) | string | Serial number of the hardware component | `CNFCP0123456789` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.vendor`](/docs/registry/attributes/hardware.md) | string | Vendor name of the hardware component | `Dell`; `HP`; `Intel`; `AMD`; `LSI`; `Lenovo` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | + + + + + + +### Metric: `hw.errors` (Tape Drive) + +This metric is [recommended][MetricRecommended]. + +Number of errors encountered by the tape drive. + +When using this metric, the following attributes MUST be set: + +- `hw.type` MUST be set to `"tape_drive"` to indicate that the errors are from a tape drive. + +The following attributes SHOULD be set: + +- `error.type` SHOULD be set to indicate the type of error, such as `"read"`, `"write"`, `"mount"`, etc. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | +| -------- | --------------- | ----------- | -------------- | --------- | ------ | +| `hw.errors` | Counter | `{error}` | Number of errors encountered by the component | ![Development](https://img.shields.io/badge/-development-blue) | | + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`hw.id`](/docs/registry/attributes/hardware.md) | string | An identifier for the hardware component, unique within the monitored host | `win32battery_battery_testsysa33_1` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.type`](/docs/registry/attributes/hardware.md) | string | Type of the component [1] | `battery`; `cpu`; `disk_controller` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`error.type`](/docs/registry/attributes/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/registry/attributes/hardware.md) | string | An easily-recognizable name for the hardware component | `eth0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.parent`](/docs/registry/attributes/hardware.md) | string | Unique identifier of the parent component (typically the `hw.id` attribute of the enclosure, or disk controller) | `dellStorage_perc_0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`network.io.direction`](/docs/registry/attributes/network.md) | string | Direction of network traffic for network errors [3] | `receive`; `transmit` | `Recommended` | ![Development](https://img.shields.io/badge/-development-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. + +**[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. | ![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 | ![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) | + +--- + +`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 | ![Development](https://img.shields.io/badge/-development-blue) | +| `transmit` | transmit | ![Development](https://img.shields.io/badge/-development-blue) | + + + + + + +### Metric: `hw.tape_drive.operations` + +This metric is [recommended][MetricRecommended]. + +Operations performed by the tape drive. + +The following attributes SHOULD be set: + +- `hw.tape_drive.operation_type` SHOULD be set to indicate the type of operation, such as `"mount"`, `"unmount"`, or `"clean"`. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | +| -------- | --------------- | ----------- | -------------- | --------- | ------ | +| `hw.tape_drive.operations` | Counter | `{operation}` | Operations performed by the tape drive | ![Development](https://img.shields.io/badge/-development-blue) | | + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`hw.id`](/docs/registry/attributes/hardware.md) | string | An identifier for the hardware component, unique within the monitored host | `win32battery_battery_testsysa33_1` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.model`](/docs/registry/attributes/hardware.md) | string | Descriptive model name of the hardware component | `PERC H740P`; `Intel(R) Core(TM) i7-10700K`; `Dell XPS 15 Battery` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.name`](/docs/registry/attributes/hardware.md) | string | An easily-recognizable name for the hardware component | `eth0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.parent`](/docs/registry/attributes/hardware.md) | string | Unique identifier of the parent component (typically the `hw.id` attribute of the enclosure, or disk controller) | `dellStorage_perc_0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.serial_number`](/docs/registry/attributes/hardware.md) | string | Serial number of the hardware component | `CNFCP0123456789` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.tape_drive.operation_type`](/docs/registry/attributes/hardware.md) | string | Type of tape drive operation | `mount`; `unmount`; `clean` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.vendor`](/docs/registry/attributes/hardware.md) | string | Vendor name of the hardware component | `Dell`; `HP`; `Intel`; `AMD`; `LSI`; `Lenovo` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | + +--- + +`hw.tape_drive.operation_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 | +|---|---|---| +| `clean` | Clean | ![Development](https://img.shields.io/badge/-development-blue) | +| `mount` | Mount | ![Development](https://img.shields.io/badge/-development-blue) | +| `unmount` | Unmount | ![Development](https://img.shields.io/badge/-development-blue) | + + + + + + +### Metric: `hw.status` (Tape Drive) + +This metric is [recommended][MetricRecommended]. + +Operational status: `1` (true) or `0` (false) for each of the possible states. + +When using this metric for tape drive status, the following attributes MUST be set: + +- `hw.type` MUST be set to `"tape_drive"` to indicate that the status is for a tape drive. +- `hw.state` MUST be set to one of the following values to indicate the tape drive state: + - `"ok"`: The tape drive is operating normally. + - `"degraded"`: The tape drive is operating with reduced functionality or performance. + - `"failed"`: The tape drive has failed and is not operational. + - `"needs_cleaning"`: The tape drive requires cleaning. + + + + + + + + +| 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. + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`hw.id`](/docs/registry/attributes/hardware.md) | string | An identifier for the hardware component, unique within the monitored host | `win32battery_battery_testsysa33_1` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.state`](/docs/registry/attributes/hardware.md) | string | The current state of the component | `degraded`; `failed`; `needs_cleaning` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.type`](/docs/registry/attributes/hardware.md) | string | Type of the component [1] | `battery`; `cpu`; `disk_controller` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.name`](/docs/registry/attributes/hardware.md) | string | An easily-recognizable name for the hardware component | `eth0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.parent`](/docs/registry/attributes/hardware.md) | string | Unique identifier of the parent component (typically the `hw.id` attribute of the enclosure, or disk controller) | `dellStorage_perc_0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-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 | ![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]: https://opentelemetry.io/docs/specs/otel/document-status +[MetricRecommended]: /docs/general/metrics.md#metric-requirement-levels diff --git a/docs/hardware/temperature.md b/docs/hardware/temperature.md new file mode 100644 index 0000000000..b398b28504 --- /dev/null +++ b/docs/hardware/temperature.md @@ -0,0 +1,200 @@ + + +# Semantic conventions for temperature metrics + +**Status**: [Development][DocumentStatus] + + + +- [Temperature metrics `hw.temperature.*`](#temperature-metrics-hwtemperature) + - [Metric: `hw.temperature`](#metric-hwtemperature) + - [Metric: `hw.temperature.limit`](#metric-hwtemperaturelimit) + - [Metric: `hw.status` (Temperature)](#metric-hwstatus-temperature) + + + +## Temperature metrics `hw.temperature.*` + +A temperature sensor, either numeric or discrete. + +`hw.type` MUST be set to `"temperature"` when using the common `hw.status` metric. + +All temperature metrics may include the below attributes: + + + + + + + + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`hw.id`](/docs/registry/attributes/hardware.md) | string | An identifier for the hardware component, unique within the monitored host | `win32battery_battery_testsysa33_1` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.name`](/docs/registry/attributes/hardware.md) | string | An easily-recognizable name for the hardware component | `eth0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.parent`](/docs/registry/attributes/hardware.md) | string | Unique identifier of the parent component (typically the `hw.id` attribute of the enclosure, or disk controller) | `dellStorage_perc_0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.sensor_location`](/docs/registry/attributes/hardware.md) | string | Location of the sensor | `cpu0`; `ps1`; `INLET`; `CPU0_DIE`; `AMBIENT`; `MOTHERBOARD`; `PS0 V3_3`; `MAIN_12V`; `CPU_VCORE` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | + + + + + + +### Metric: `hw.temperature` + +This metric is [recommended][MetricRecommended]. + +Temperature in degrees Celsius. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | +| -------- | --------------- | ----------- | -------------- | --------- | ------ | +| `hw.temperature` | Gauge | `Cel` | Temperature in degrees Celsius | ![Development](https://img.shields.io/badge/-development-blue) | | + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`hw.id`](/docs/registry/attributes/hardware.md) | string | An identifier for the hardware component, unique within the monitored host | `win32battery_battery_testsysa33_1` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.name`](/docs/registry/attributes/hardware.md) | string | An easily-recognizable name for the hardware component | `eth0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.parent`](/docs/registry/attributes/hardware.md) | string | Unique identifier of the parent component (typically the `hw.id` attribute of the enclosure, or disk controller) | `dellStorage_perc_0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.sensor_location`](/docs/registry/attributes/hardware.md) | string | Location of the sensor | `cpu0`; `ps1`; `INLET`; `CPU0_DIE`; `AMBIENT`; `MOTHERBOARD`; `PS0 V3_3`; `MAIN_12V`; `CPU_VCORE` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | + + + + + + +### Metric: `hw.temperature.limit` + +This metric is [recommended][MetricRecommended]. + +Temperature limit in degrees Celsius. + +The following attributes SHOULD be set: + +- `hw.temperature.limit_type` SHOULD be set to indicate the type of limit, such as `"low.critical"`, `"low.degraded"`, `"high.degraded"`, or `"high.critical"`. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | +| -------- | --------------- | ----------- | -------------- | --------- | ------ | +| `hw.temperature.limit` | Gauge | `Cel` | Temperature limit in degrees Celsius | ![Development](https://img.shields.io/badge/-development-blue) | | + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`hw.id`](/docs/registry/attributes/hardware.md) | string | An identifier for the hardware component, unique within the monitored host | `win32battery_battery_testsysa33_1` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.limit_type`](/docs/registry/attributes/hardware.md) | string | Type of limit for hardware components | `low.critical`; `low.degraded`; `high.degraded`; `high.critical` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.name`](/docs/registry/attributes/hardware.md) | string | An easily-recognizable name for the hardware component | `eth0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.parent`](/docs/registry/attributes/hardware.md) | string | Unique identifier of the parent component (typically the `hw.id` attribute of the enclosure, or disk controller) | `dellStorage_perc_0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.sensor_location`](/docs/registry/attributes/hardware.md) | string | Location of the sensor | `cpu0`; `ps1`; `INLET`; `CPU0_DIE`; `AMBIENT`; `MOTHERBOARD`; `PS0 V3_3`; `MAIN_12V`; `CPU_VCORE` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | + +--- + +`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.status` (Temperature) + +This metric is [recommended][MetricRecommended]. + +Whether the temperature is within normal range: `1` (true) or `0` (false) for each of the possible states. + +When using this metric for temperature status, the following attributes MUST be set: + +- `hw.type` MUST be set to `"temperature"` to indicate that the status is for a temperature sensor. +- `hw.state` MUST be set to one of the following values to indicate the temperature state: + - `"ok"`: The temperature is within normal range. + - `"degraded"`: The temperature is outside the normal range but not critical. + - `"failed"`: The temperature is at a critical level. + + + + + + + + +| 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. + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`hw.id`](/docs/registry/attributes/hardware.md) | string | An identifier for the hardware component, unique within the monitored host | `win32battery_battery_testsysa33_1` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.state`](/docs/registry/attributes/hardware.md) | string | The current state of the component | `degraded`; `failed`; `needs_cleaning` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.type`](/docs/registry/attributes/hardware.md) | string | Type of the component [1] | `battery`; `cpu`; `disk_controller` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.name`](/docs/registry/attributes/hardware.md) | string | An easily-recognizable name for the hardware component | `eth0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.parent`](/docs/registry/attributes/hardware.md) | string | Unique identifier of the parent component (typically the `hw.id` attribute of the enclosure, or disk controller) | `dellStorage_perc_0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-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 | ![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]: https://opentelemetry.io/docs/specs/otel/document-status +[MetricRecommended]: /docs/general/metrics.md#metric-requirement-levels diff --git a/docs/hardware/voltage.md b/docs/hardware/voltage.md new file mode 100644 index 0000000000..8d9b310faa --- /dev/null +++ b/docs/hardware/voltage.md @@ -0,0 +1,230 @@ + + +# Semantic conventions for voltage metrics + +**Status**: [Development][DocumentStatus] + + + +- [Voltage metrics `hw.voltage.*`](#voltage-metrics-hwvoltage) + - [Metric: `hw.voltage`](#metric-hwvoltage) + - [Metric: `hw.voltage.limit`](#metric-hwvoltagelimit) + - [Metric: `hw.voltage.nominal`](#metric-hwvoltagenominal) + - [Metric: `hw.status` (Voltage)](#metric-hwstatus-voltage) + + + +## Voltage metrics `hw.voltage.*` + +A voltage sensor, either numeric or discrete. + +`hw.type` MUST be set to `"voltage"` when using the common `hw.status` metric. + +All voltage metrics may include the below attributes: + + + + + + + + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`hw.id`](/docs/registry/attributes/hardware.md) | string | An identifier for the hardware component, unique within the monitored host | `win32battery_battery_testsysa33_1` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.name`](/docs/registry/attributes/hardware.md) | string | An easily-recognizable name for the hardware component | `eth0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.parent`](/docs/registry/attributes/hardware.md) | string | Unique identifier of the parent component (typically the `hw.id` attribute of the enclosure, or disk controller) | `dellStorage_perc_0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.sensor_location`](/docs/registry/attributes/hardware.md) | string | Location of the sensor | `cpu0`; `ps1`; `INLET`; `CPU0_DIE`; `AMBIENT`; `MOTHERBOARD`; `PS0 V3_3`; `MAIN_12V`; `CPU_VCORE` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | + + + + + + +### Metric: `hw.voltage` + +This metric is [recommended][MetricRecommended]. + +Voltage measured by the sensor. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | +| -------- | --------------- | ----------- | -------------- | --------- | ------ | +| `hw.voltage` | Gauge | `V` | Voltage measured by the sensor | ![Development](https://img.shields.io/badge/-development-blue) | | + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`hw.id`](/docs/registry/attributes/hardware.md) | string | An identifier for the hardware component, unique within the monitored host | `win32battery_battery_testsysa33_1` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.name`](/docs/registry/attributes/hardware.md) | string | An easily-recognizable name for the hardware component | `eth0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.parent`](/docs/registry/attributes/hardware.md) | string | Unique identifier of the parent component (typically the `hw.id` attribute of the enclosure, or disk controller) | `dellStorage_perc_0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.sensor_location`](/docs/registry/attributes/hardware.md) | string | Location of the sensor | `cpu0`; `ps1`; `INLET`; `CPU0_DIE`; `AMBIENT`; `MOTHERBOARD`; `PS0 V3_3`; `MAIN_12V`; `CPU_VCORE` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | + + + + + + +### Metric: `hw.voltage.limit` + +This metric is [recommended][MetricRecommended]. + +Voltage limit in Volts. + +The following attributes SHOULD be set: + +- `hw.voltage.limit_type` SHOULD be set to indicate the type of limit, such as `"low.critical"`, `"low.degraded"`, `"high.degraded"`, or `"high.critical"`. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | +| -------- | --------------- | ----------- | -------------- | --------- | ------ | +| `hw.voltage.limit` | Gauge | `V` | Voltage limit in Volts | ![Development](https://img.shields.io/badge/-development-blue) | | + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`hw.id`](/docs/registry/attributes/hardware.md) | string | An identifier for the hardware component, unique within the monitored host | `win32battery_battery_testsysa33_1` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.limit_type`](/docs/registry/attributes/hardware.md) | string | Type of limit for hardware components | `low.critical`; `low.degraded`; `high.degraded`; `high.critical` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.name`](/docs/registry/attributes/hardware.md) | string | An easily-recognizable name for the hardware component | `eth0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.parent`](/docs/registry/attributes/hardware.md) | string | Unique identifier of the parent component (typically the `hw.id` attribute of the enclosure, or disk controller) | `dellStorage_perc_0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.sensor_location`](/docs/registry/attributes/hardware.md) | string | Location of the sensor | `cpu0`; `ps1`; `INLET`; `CPU0_DIE`; `AMBIENT`; `MOTHERBOARD`; `PS0 V3_3`; `MAIN_12V`; `CPU_VCORE` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | + +--- + +`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.voltage.nominal` + +This metric is [recommended][MetricRecommended]. + +Nominal (expected) voltage. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | +| -------- | --------------- | ----------- | -------------- | --------- | ------ | +| `hw.voltage.nominal` | Gauge | `V` | Nominal (expected) voltage | ![Development](https://img.shields.io/badge/-development-blue) | | + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`hw.id`](/docs/registry/attributes/hardware.md) | string | An identifier for the hardware component, unique within the monitored host | `win32battery_battery_testsysa33_1` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.name`](/docs/registry/attributes/hardware.md) | string | An easily-recognizable name for the hardware component | `eth0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.parent`](/docs/registry/attributes/hardware.md) | string | Unique identifier of the parent component (typically the `hw.id` attribute of the enclosure, or disk controller) | `dellStorage_perc_0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.sensor_location`](/docs/registry/attributes/hardware.md) | string | Location of the sensor | `cpu0`; `ps1`; `INLET`; `CPU0_DIE`; `AMBIENT`; `MOTHERBOARD`; `PS0 V3_3`; `MAIN_12V`; `CPU_VCORE` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | + + + + + + +### Metric: `hw.status` (Voltage) + +This metric is [recommended][MetricRecommended]. + +Whether the voltage is within normal range: `1` (true) or `0` (false) for each of the possible states. + +When using this metric for voltage status, the following attributes MUST be set: + +- `hw.type` MUST be set to `"voltage"` to indicate that the status is for a voltage sensor. +- `hw.state` MUST be set to one of the following values to indicate the voltage state: + - `"ok"`: The voltage is within normal range. + - `"degraded"`: The voltage is outside the normal range but not critical. + - `"failed"`: The voltage is at a critical level. + + + + + + + + +| 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. + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`hw.id`](/docs/registry/attributes/hardware.md) | string | An identifier for the hardware component, unique within the monitored host | `win32battery_battery_testsysa33_1` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.state`](/docs/registry/attributes/hardware.md) | string | The current state of the component | `degraded`; `failed`; `needs_cleaning` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.type`](/docs/registry/attributes/hardware.md) | string | Type of the component [1] | `battery`; `cpu`; `disk_controller` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.name`](/docs/registry/attributes/hardware.md) | string | An easily-recognizable name for the hardware component | `eth0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`hw.parent`](/docs/registry/attributes/hardware.md) | string | Unique identifier of the parent component (typically the `hw.id` attribute of the enclosure, or disk controller) | `dellStorage_perc_0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-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 | ![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]: https://opentelemetry.io/docs/specs/otel/document-status +[MetricRecommended]: /docs/general/metrics.md#metric-requirement-levels diff --git a/docs/registry/attributes/hardware.md b/docs/registry/attributes/hardware.md index c52881da51..2445fac5f4 100644 --- a/docs/registry/attributes/hardware.md +++ b/docs/registry/attributes/hardware.md @@ -9,23 +9,109 @@ Attributes for hardware. | Attribute | Type | Description | Examples | Stability | |---|---|---|---|---| +| `hw.battery.capacity` | string | Design capacity in Watts-hours or Amper-hours | `9.3Ah`; `50Wh` | ![Development](https://img.shields.io/badge/-development-blue) | +| `hw.battery.chemistry` | 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` | ![Development](https://img.shields.io/badge/-development-blue) | +| `hw.battery.state` | string | The current state of the battery | `charging`; `discharging` | ![Development](https://img.shields.io/badge/-development-blue) | +| `hw.bios_version` | string | BIOS version of the hardware component | `1.2.3` | ![Development](https://img.shields.io/badge/-development-blue) | +| `hw.driver_version` | string | Driver version for the hardware component | `10.2.1-3` | ![Development](https://img.shields.io/badge/-development-blue) | +| `hw.enclosure.type` | string | Type of the enclosure (useful for modular systems) | `Computer`; `Storage`; `Switch` | ![Development](https://img.shields.io/badge/-development-blue) | +| `hw.firmware_version` | string | Firmware version of the hardware component | `2.0.1` | ![Development](https://img.shields.io/badge/-development-blue) | +| `hw.gpu.task` | string | Type of task the GPU is performing | `decoder`; `encoder`; `general` | ![Development](https://img.shields.io/badge/-development-blue) | | `hw.id` | string | An identifier for the hardware component, unique within the monitored host | `win32battery_battery_testsysa33_1` | ![Development](https://img.shields.io/badge/-development-blue) | +| `hw.limit_type` | string | Type of limit for hardware components | `critical`; `degraded`; `high.critical` | ![Development](https://img.shields.io/badge/-development-blue) | +| `hw.logical_disk.raid_level` | string | RAID Level of the logical disk | `RAID0+1`; `RAID5`; `RAID10` | ![Development](https://img.shields.io/badge/-development-blue) | +| `hw.logical_disk.state` | string | State of the logical disk space usage | `used`; `free` | ![Development](https://img.shields.io/badge/-development-blue) | +| `hw.memory.type` | string | Type of the memory module | `DDR4`; `DDR5`; `LPDDR5` | ![Development](https://img.shields.io/badge/-development-blue) | +| `hw.model` | string | Descriptive model name of the hardware component | `PERC H740P`; `Intel(R) Core(TM) i7-10700K`; `Dell XPS 15 Battery` | ![Development](https://img.shields.io/badge/-development-blue) | | `hw.name` | string | An easily-recognizable name for the hardware component | `eth0` | ![Development](https://img.shields.io/badge/-development-blue) | +| `hw.network.logical_addresses` | string[] | Logical addresses of the adapter (e.g. IP address, or WWPN) | `["172.16.8.21", "57.11.193.42"]` | ![Development](https://img.shields.io/badge/-development-blue) | +| `hw.network.physical_address` | string | Physical address of the adapter (e.g. MAC address, or WWNN) | `00-90-F5-E9-7B-36` | ![Development](https://img.shields.io/badge/-development-blue) | | `hw.parent` | string | Unique identifier of the parent component (typically the `hw.id` attribute of the enclosure, or disk controller) | `dellStorage_perc_0` | ![Development](https://img.shields.io/badge/-development-blue) | -| `hw.state` | string | The current state of the component | `ok`; `degraded`; `failed` | ![Development](https://img.shields.io/badge/-development-blue) | +| `hw.physical_disk.smart_attribute` | string | [S.M.A.R.T.](https://wikipedia.org/wiki/S.M.A.R.T.) (Self-Monitoring, Analysis, and Reporting Technology) attribute of the physical disk | `Spin Retry Count`; `Seek Error Rate`; `Raw Read Error Rate` | ![Development](https://img.shields.io/badge/-development-blue) | +| `hw.physical_disk.state` | string | State of the physical disk endurance utilization | `remaining` | ![Development](https://img.shields.io/badge/-development-blue) | +| `hw.physical_disk.type` | string | Type of the physical disk | `HDD`; `SSD`; `10K` | ![Development](https://img.shields.io/badge/-development-blue) | +| `hw.sensor_location` | string | Location of the sensor | `cpu0`; `ps1`; `INLET`; `CPU0_DIE`; `AMBIENT`; `MOTHERBOARD`; `PS0 V3_3`; `MAIN_12V`; `CPU_VCORE` | ![Development](https://img.shields.io/badge/-development-blue) | +| `hw.serial_number` | string | Serial number of the hardware component | `CNFCP0123456789` | ![Development](https://img.shields.io/badge/-development-blue) | +| `hw.state` | string | The current state of the component | `degraded`; `failed`; `needs_cleaning` | ![Development](https://img.shields.io/badge/-development-blue) | +| `hw.tape_drive.operation_type` | string | Type of tape drive operation | `mount`; `unmount`; `clean` | ![Development](https://img.shields.io/badge/-development-blue) | | `hw.type` | string | Type of the component [1] | `battery`; `cpu`; `disk_controller` | ![Development](https://img.shields.io/badge/-development-blue) | +| `hw.vendor` | string | Vendor name of the hardware component | `Dell`; `HP`; `Intel`; `AMD`; `LSI`; `Lenovo` | ![Development](https://img.shields.io/badge/-development-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.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.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 | ![Development](https://img.shields.io/badge/-development-blue) | +| `encoder` | Encoder | ![Development](https://img.shields.io/badge/-development-blue) | +| `general` | General | ![Development](https://img.shields.io/badge/-development-blue) | + +--- + +`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) | + +--- + +`hw.logical_disk.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 | +|---|---|---| +| `free` | Free | ![Development](https://img.shields.io/badge/-development-blue) | +| `used` | Used | ![Development](https://img.shields.io/badge/-development-blue) | + +--- + +`hw.physical_disk.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 | +|---|---|---| +| `remaining` | Remaining | ![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) | -| `ok` | Ok | ![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.tape_drive.operation_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 | +|---|---|---| +| `clean` | Clean | ![Development](https://img.shields.io/badge/-development-blue) | +| `mount` | Mount | ![Development](https://img.shields.io/badge/-development-blue) | +| `unmount` | Unmount | ![Development](https://img.shields.io/badge/-development-blue) | --- diff --git a/docs/system/README.md b/docs/system/README.md index 24ac1c7c51..8cc7e0647d 100644 --- a/docs/system/README.md +++ b/docs/system/README.md @@ -13,7 +13,7 @@ System semantic conventions are defined for the following metrics: * [System](system-metrics.md): For standard system metrics. * [Container](container-metrics.md): For container-related metrics. * [K8s](k8s-metrics.md): For K8s-related metrics. -* [Hardware](hardware-metrics.md): For hardware-related metrics. +* [Hardware](../hardware/README.md): For hardware-related metrics. * [Process](process-metrics.md): For standard process metrics. * [Runtime Environment](/docs/runtime/README.md#metrics): For runtime environment metrics. diff --git a/docs/system/hardware-metrics.md b/docs/system/hardware-metrics.md deleted file mode 100644 index ff23e3ce53..0000000000 --- a/docs/system/hardware-metrics.md +++ /dev/null @@ -1,352 +0,0 @@ - - -# Semantic conventions for hardware metrics - -**Status**: [Development][DocumentStatus] - -This document describes instruments and attributes for common hardware level -metrics in OpenTelemetry. Consider the [general metric semantic conventions](/docs/general/metrics.md#general-guidelines) -when creating instruments not explicitly defined in the specification. - -This document is being converted to specific hardware metrics, parts of this document that have already been -converted are now located in the [Hardware](/docs/hardware/README.md) folder and are no longer present in this file. - -Please note that this is an [ongoing process](https://github.com/open-telemetry/semantic-conventions/issues/1309) and may take some time to complete. - - - -- [Common hardware attributes](/docs/registry/attributes/hardware.md) -- [Metric Instruments](#metric-instruments) - - [`hw.` - Common hardware metrics](/docs/hardware/common.md) - - [`hw.host.` - Physical host metrics](/docs/hardware/host.md) - - [`hw.battery.` - Battery metrics](#hwbattery---battery-metrics) - - [`hw.cpu.` - Physical processor metrics](#hwcpu---physical-processor-metrics) - - [`hw.disk_controller.` - Disk controller metrics](#hwdisk_controller---disk-controller-metrics) - - [`hw.enclosure.` - Enclosure metrics](#hwenclosure---enclosure-metrics) - - [`hw.fan.` - Fan metrics](#hwfan---fan-metrics) - - [`hw.gpu.` - GPU metrics](#hwgpu---gpu-metrics) - - [`hw.logical_disk.`- Logical disk metrics](#hwlogical_disk--logical-disk-metrics) - - [`hw.memory.` - Memory module metrics](#hwmemory---memory-module-metrics) - - [`hw.network.` - Network adapter metrics](#hwnetwork---network-adapter-metrics) - - [`hw.physical_disk.`- Physical disk metrics](#hwphysical_disk--physical-disk-metrics) - - [`hw.power_supply.` - Power supply metrics](#hwpower_supply---power-supply-metrics) - - [`hw.tape_drive.` - Tape drive metrics](#hwtape_drive---tape-drive-metrics) - - [`hw.temperature.` - Temperature sensor metrics](#hwtemperature---temperature-sensor-metrics) - - [`hw.voltage.` - Voltage sensor metrics](#hwvoltage---voltage-sensor-metrics) - -> **Warning** -> Existing instrumentations and collector that are using -> [v1.21.0 of this document](https://github.com/open-telemetry/semantic-conventions/blob/v1.21.0/docs/system/hardware-metrics.md) -> (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. - -## Metric instruments - -### `hw.battery.` - Battery metrics - -**Description:** A battery in a computer system or an UPS. - -| Name | Description | Units | Instrument Type ([*](/docs/general/metrics.md#instrument-types)) | 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 ([*](/docs/general/metrics.md#instrument-types)) | 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` | - -Additional **Recommended** attributes: - -| Attribute Key | Description | Example | -| ------------- | ---------------------- | ------- | -| `model` | Descriptive model name | | -| `vendor` | Vendor name | | - -### `hw.disk_controller.` - Disk controller metrics - -**Description:** Controller that controls the physical disks and organize -them in RAID sets and logical disks that are exposed to the operating system. - -| Name | Description | Units | Instrument Type ([*](/docs/general/metrics.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | -| ----------- | ----------------------------------------------------------------------------- | ----- | ------------------------------------------------- | ---------- | ------------------------ | -------------------------- | -| `hw.status` | Operational status: `1` (true) or `0` (false) for each of the possible states | | UpDownCounter | Int | `state` (**Required**) | `ok`, `degraded`, `failed` | -| | | | | | `hw.type` (**Required**) | `disk_controller` | - -Additional **Recommended** attributes: - -| Attribute Key | Description | Example | -| ------------------ | ------------------------- | ------- | -| `bios_version` | BIOS version | | -| `driver_version` | Driver for the controller | | -| `firmware_version` | Firmware version | | -| `model` | Descriptive model name | | -| `serial_number` | Serial number | | -| `vendor` | Vendor name | | - -### `hw.enclosure.` - Enclosure metrics - -**Description:** Computer chassis (can be an expansion enclosure) - -| Name | Description | Units | Instrument Type ([*](/docs/general/metrics.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | -| ----------- | ----------------------------------------------------------------------------- | ----- | ------------------------------------------------- | ---------- | ------------------------ | ---------------------------------- | -| `hw.status` | Operational status: `1` (true) or `0` (false) for each of the possible states | | UpDownCounter | Int | `state` (**Required**) | `ok`, `degraded`, `failed`, `open` | -| | | | | | `hw.type` (**Required**) | `enclosure` | - -Additional **Recommended** attributes: - -| Attribute Key | Description | Example | -| --------------- | -------------------------------------------------- | ------------------------- | -| `bios_version` | BIOS version | | -| `model` | Descriptive model name | | -| `serial_number` | Serial number | | -| `type` | Type of the enclosure (useful for modular systems) | Computer, Storage, Switch | -| `vendor` | Vendor name | | - -### `hw.fan.` - Fan metrics - -**Description:** Fan that keeps the air flowing to maintain the internal -temperature of a computer - -| Name | Description | Units | Instrument Type ([*](/docs/general/metrics.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | -| -------------------- | ----------------------------------------------------------------------------- | ----- | ------------------------------------------------- | ---------- | ------------------------------ | ------------------------------------- | -| `hw.fan.speed` | Fan speed in revolutions per minute | rpm | Gauge | Int | | | -| `hw.fan.speed.limit` | Speed limit in rpm | rpm | Gauge | Int | `limit_type` (**Recommended**) | `low.critical`, `low.degraded`, `max` | -| `hw.fan.speed_ratio` | Fan speed expressed as a fraction of its maximum speed | 1 | Gauge | Double | | | -| `hw.status` | Operational status: `1` (true) or `0` (false) for each of the possible states | | UpDownCounter | Int | `state` (**Required**) | `ok`, `degraded`, `failed` | -| | | | | | `hw.type` (**Required**) | `fan` | - -Additional **Recommended** attributes: - -| Attribute Key | Description | Example | -| ----------------- | --------------------------------------------- | ---------------- | -| `sensor_location` | Location of the fan in the computer enclosure | cpu0, ps1, INLET | - -### `hw.gpu.` - GPU metrics - -**Description:** Graphics Processing Unit (discrete) - -| Name | Description | Units | Instrument Type ([*](/docs/general/metrics.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | -| --------------------------- | ----------------------------------------------------------------------------- | ------- | ------------------------------------------------- | ---------- | ----------------------------- | ----------------------------------------------- | -| `hw.errors` | Number of errors encountered by the GPU | {error} | Counter | Int64 | `hw.error.type` (Recommended) | `corrected`, `uncorrected` | -| | | | | | `hw.type` (**Required**) | `gpu` | -| `hw.gpu.io` | Received and transmitted bytes by the GPU | By | Counter | Int64 | `direction` (**Required**) | `receive`, `transmit` | -| `hw.gpu.memory.limit` | Size of the GPU memory | By | UpDownCounter | Int64 | | | -| `hw.gpu.memory.utilization` | Fraction of GPU memory used | 1 | Gauge | Double | | | -| `hw.gpu.memory.usage` | GPU memory used | By | UpDownCounter | Int64 | | | -| `hw.gpu.power` | GPU instantaneous power consumption in Watts | W | Gauge | Double | | | -| `hw.gpu.utilization` | Fraction of time spent in a specific task | 1 | Gauge | Double | `task` (Recommended) | `decoder`, `encoder`, `general` | -| `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**) | `gpu` | - -Additional **Recommended** attributes: - -| Attribute Key | Description | Example | -| ------------------ | ------------------------- | ------- | -| `driver_version` | Driver for the controller | | -| `firmware_version` | Firmware version | | -| `model` | Descriptive model name | | -| `serial_number` | Serial number | | -| `vendor` | Vendor name | | - -### `hw.logical_disk.`- Logical disk metrics - -**Description:** Storage extent presented as a physical disk by a disk -controller to the operating system (e.g. a RAID 1 set made of 2 disks, and exposed -as /dev/hdd0 by the controller). - -| Name | Description | Units | Instrument Type ([*](/docs/general/metrics.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | -| ----------------------------- | ----------------------------------------------------------------------------- | ------- | ------------------------------------------------- | ---------- | ------------------------ | -------------------------- | -| `hw.errors` | Number of errors encountered on this logical disk | {error} | Counter | Int64 | `hw.type` (**Required**) | `logical_disk` | -| `hw.logical_disk.limit` | Size of the logical disk | By | UpDownCounter | Int64 | | | -| `hw.logical_disk.usage` | Logical disk space usage | By | UpDownCounter | Int64 | `state` (**Required**) | `used`, `free` | -| `hw.logical_disk.utilization` | Logical disk space utilization as a fraction | 1 | Gauge | Double | `state` (**Required**) | `used`, `free` | -| `hw.status` | Operational status: `1` (true) or `0` (false) for each of the possible states | | UpDownCounter | Int | `state` (**Required**) | `ok`, `degraded`, `failed` | -| | | | | | `hw.type` (**Required**) | `logical_disk` | - -Additional **Recommended** attributes: - -| Attribute Key | Description | Example | -| ------------- | ----------- | --------- | -| `raid_level` | RAID Level | `RAID0+1` | - -### `hw.memory.` - Memory module metrics - -**Description:** A memory module in a computer system. - -| Name | Description | Units | Instrument Type ([*](/docs/general/metrics.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | -| ---------------- | ----------------------------------------------------------------------------- | ------- | ------------------------------------------------- | ---------- | ------------------------ | ----------------------------------------------- | -| `hw.errors` | Number of errors encountered on this memory module | {error} | Counter | Int64 | `hw.type` (**Required**) | `memory` | -| `hw.memory.size` | Size of the memory module | By | UpDownCounter | Int64 | | | -| `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**) | `memory` | - -Additional **Recommended** attributes: - -| Attribute Key | Description | Example | -| --------------- | ------------------------- | ------- | -| `model` | Descriptive model name | | -| `serial_number` | Serial number | | -| `type` | Type of the memory module | `DDR5` | -| `vendor` | Vendor name | | - -### `hw.network.` - Network adapter metrics - -**Description:** 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. - -| Name | Description | Units | Instrument Type ([*](/docs/general/metrics.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | -| ---------------------------------- | ------------------------------------------------------------------------------------------------------------ | -------- | ------------------------------------------------- | ---------- | ----------------------------- | --------------------------------- | -| `hw.errors` | Number of errors encountered by the network adapter | {error} | Counter | Int64 | `hw.error.type` (Recommended) | `zero_buffer_credit`, `crc`, etc. | -| | | | | | `hw.type` (**Required**) | `network` | -| | | | | | `direction` (Recommended) | `receive`, `transmit` | -| `hw.network.bandwidth.limit` | Link speed | By/s | UpDownCounter | Int64 | | | -| `hw.network.bandwidth.utilization` | Utilization of the network bandwidth as a fraction | 1 | Gauge | Double | | | -| `hw.network.io` | Received and transmitted network traffic in bytes | By | Counter | Int64 | `direction` (**Required**) | `receive`, `transmit` | -| `hw.network.packets` | Received and transmitted network traffic in packets (or frames) | {packet} | Counter | Int64 | `direction` (**Required**) | `receive`, `transmit` | -| `hw.network.up` | Link status: `1` (up) or `0` (down) | | UpDownCounter | Int | | | -| `hw.status` | Operational status, regardless of the link status: `1` (true) or `0` (false) for each of the possible states | | UpDownCounter | Int | `state` (**Required**) | `ok`, `degraded`, `failed` | -| | | | | | `hw.type` (**Required**) | `network` | - -Additional **Recommended** attributes: - -| Attribute Key | Description | Example | -| ------------------- | ----------------------------------------------------------- | --------------------------- | -| `model` | Descriptive model name | | -| `logical_addresses` | Logical addresses of the adapter (e.g. IP address, or WWPN) | `172.16.8.21, 57.11.193.42` | -| `physical_address` | Physical address of the adapter (e.g. MAC address, or WWNN) | `00-90-F5-E9-7B-36` | -| `serial_number` | Serial number | | -| `vendor` | Vendor name | | - -### `hw.physical_disk.`- Physical disk metrics - -**Description:** Physical hard drive (HDD or SDD) - -| Name | Description | Units | Instrument Type ([*](/docs/general/metrics.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | -| ---------------------------------------- | ------------------------------------------------------------------------------------------- | ------- | ------------------------------------------------- | ---------- | ------------------------------- | ----------------------------------------------- | -| `hw.errors` | Number of errors encountered on this disk | {error} | Counter | Int64 | `hw.error.type` (Recommended) | `bad_sector`, `write`, etc. | -| | | | | | `hw.type` (**Required**) | `physical_disk` | -| `hw.physical_disk.endurance_utilization` | Endurance remaining for this SSD disk | 1 | Gauge | Double | `state` (**Required**) | `remaining` | -| `hw.physical_disk.size` | Size of the disk | By | UpDownCounter | Int64 | | | -| `hw.physical_disk.smart` | Value of the corresponding [S.M.A.R.T.](https://wikipedia.org/wiki/S.M.A.R.T.) attribute | 1 | Gauge | Int | `smart_attribute` (Recommended) | `Seek Error Rate`, `Spin Retry Count`, etc. | -| `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**) | `physical_disk` | - -Additional **Recommended** attributes: - -| Attribute Key | Description | Example | -| ------------------ | ---------------------- | ------------------- | -| `firmware_version` | Firmware version | | -| `model` | Descriptive model name | | -| `serial_number` | Serial number | | -| `type` | Type of the disk | `HDD`, `SSD`, `10K` | -| `vendor` | Vendor name | | - -### `hw.power_supply.` - Power supply metrics - -**Description:** Power supply converting AC current to DC used by the -motherboard and the GPUs - -| Name | Description | Units | Instrument Type ([*](/docs/general/metrics.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | -| ----------------------------- | ----------------------------------------------------------------------------- | ----- | ------------------------------------------------- | ---------- | -------------------------- | ------------------------------ | -| `hw.power_supply.limit` | Maximum power output of the power supply | W | UpDownCounter | Int64 | `limit_type` (Recommended) | `max`, `critical`, `throttled` | -| `hw.power_supply.utilization` | Utilization of the power supply as a fraction of its maximum output | 1 | Gauge | Double | | | -| `hw.status` | Operational status: `1` (true) or `0` (false) for each of the possible states | | UpDownCounter | Int | `state` (**Required**) | `ok`, `degraded`, `failed` | -| | | | | | `hw.type` (**Required**) | `power_supply` | - -Additional **Recommended** attributes: - -| Attribute Key | Description | Example | -| --------------- | ---------------------- | ------- | -| `model` | Descriptive model name | | -| `serial_number` | Serial number | | -| `vendor` | Vendor name | | - -### `hw.tape_drive.` - Tape drive metrics - -**Description:** A tape drive in a computer or in a tape library (excluding -virtual tape libraries) - -| Name | Description | Units | Instrument Type ([*](/docs/general/metrics.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | -| -------------------------- | ----------------------------------------------------------------------------- | ----------- | ------------------------------------------------- | ---------- | ------------------------ | -------------------------------------------- | -| `hw.errors` | Number of errors encountered by the tape drive | {error} | Counter | Int64 | `hw.error.type` | `read`, `write`, `mount`, etc. | -| | | | | | `hw.type` (**Required**) | `tape_drive` | -| `hw.tape_drive.operations` | Operations performed by the tape drive | {operation} | Counter | Int64 | `type` (Recommended) | `mount`, `unmount`, `clean` | -| `hw.status` | Operational status: `1` (true) or `0` (false) for each of the possible states | | UpDownCounter | Int | `state` (**Required**) | `ok`, `degraded`, `failed`, `needs_cleaning` | -| | | | | | `hw.type` (**Required**) | `tape_drive` | - -Additional **Recommended** attributes: - -| Attribute Key | Description | Example | -| --------------- | ---------------------- | ------- | -| `model` | Descriptive model name | | -| `serial_number` | Serial number | | -| `vendor` | Vendor name | | - -### `hw.temperature.` - Temperature sensor metrics - -**Description:** A temperature sensor, either numeric or discrete - -| Name | Description | Units | Instrument Type ([*](/docs/general/metrics.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | -| ---------------------- | --------------------------------------------------------------------------------------------------------- | ----- | ------------------------------------------------- | ---------- | -------------------------- | ---------------------------------------------------------------- | -| `hw.temperature` | Temperature in degrees Celsius | Cel | Gauge | Double | | | -| `hw.temperature.limit` | Temperature limit in degrees Celsius | Cel | Gauge | Double | `limit_type` (Recommended) | `low.critical`, `low.degraded`, `high.degraded`, `high.critical` | -| `hw.status` | Whether the temperature is within normal range: `1` (true) or `0` (false) for each of the possible states | | UpDownCounter | Int | `state` (**Required**) | `ok`, `degraded`, `failed` | -| | | | | | `hw.type` (**Required**) | `temperature` | - -Additional **Recommended** attributes: - -| Attribute Key | Description | Example | -| ----------------- | ---------------------- | ---------- | -| `sensor_location` | Location of the sensor | `CPU0_DIE` | - -### `hw.voltage.` - Voltage sensor metrics - -**Description:** A voltage sensor, either numeric or discrete - -| Name | Description | Units | Instrument Type ([*](/docs/general/metrics.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | -| -------------------- | ----------------------------------------------------------------------------------------------------- | ----- | ------------------------------------------------- | ---------- | -------------------------- | ---------------------------------------------------------------- | -| `hw.voltage.limit` | Voltage limit in Volts | V | Gauge | Double | `limit_type` (Recommended) | `low.critical`, `low.degraded`, `high.degraded`, `high.critical` | -| `hw.voltage.nominal` | Nominal (expected) voltage | V | Gauge | Double | | | -| `hw.voltage` | Voltage measured by the sensor | V | Gauge | Double | | | -| `hw.status` | Whether the voltage is within normal range: `1` (true) or `0` (false) for each of the possible states | | UpDownCounter | Int | `state` (**Required**) | `ok`, `degraded`, `failed` | -| | | | | | `hw.type` (**Required**) | `voltage` | - -Additional **Recommended** attributes: - -| Attribute Key | Description | Example | -| ----------------- | ---------------------- | ---------- | -| `sensor_location` | Location of the sensor | `PS0 V3_3` | - -[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status diff --git a/model/hardware/battery-metrics.yaml b/model/hardware/battery-metrics.yaml new file mode 100644 index 0000000000..7dd3ae0573 --- /dev/null +++ b/model/hardware/battery-metrics.yaml @@ -0,0 +1,72 @@ +groups: + # BATTERY METRICS + - id: metric.hw.battery + type: attribute_group + brief: > + Common attributes for battery metrics + extends: hardware.attributes.common + attributes: + - ref: hw.battery.chemistry + requirement_level: recommended + - ref: hw.battery.capacity + requirement_level: recommended + - ref: hw.model + requirement_level: recommended + - ref: hw.vendor + requirement_level: recommended + + - id: metric.hw.battery.charge + type: metric + metric_name: hw.battery.charge + annotations: + code_generation: + metric_value_type: double + stability: development + brief: "Remaining fraction of battery charge" + instrument: gauge + unit: "1" + extends: metric.hw.battery + + # TODO: decide on metric name - charge.limit is original + - id: metric.hw.battery.charge.limit + type: metric + metric_name: hw.battery.charge.limit + annotations: + code_generation: + metric_value_type: double + stability: development + brief: "Lower limit of battery charge fraction to ensure proper operation" + instrument: gauge + unit: "1" + extends: metric.hw.battery + attributes: + - ref: hw.limit_type + examples: ["critical", "throttled", "degraded"] + requirement_level: recommended + brief: > + 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. + + - id: metric.hw.battery.time_left + type: metric + metric_name: hw.battery.time_left + annotations: + code_generation: + metric_value_type: int + stability: development + brief: "Time left before battery is completely charged or discharged" + instrument: gauge + unit: "s" + extends: metric.hw.battery + attributes: + - ref: hw.state + requirement_level: required + - ref: hw.battery.state + requirement_level: + conditionally_required: If the battery is charging or discharging + note: > + 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". diff --git a/model/hardware/common-metrics.yaml b/model/hardware/common-metrics.yaml index f9addeb1b9..bc270b53e7 100644 --- a/model/hardware/common-metrics.yaml +++ b/model/hardware/common-metrics.yaml @@ -40,6 +40,12 @@ groups: note: > 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. + - ref: network.io.direction + brief: "Direction of network traffic for network errors" + examples: ['receive', 'transmit'] + requirement_level: recommended + note: > + This attribute SHOULD only be used when `hw.type` is set to `"network"` to indicate the direction of the error. - id: metric.hw.power type: metric diff --git a/model/hardware/cpu-metrics.yaml b/model/hardware/cpu-metrics.yaml new file mode 100644 index 0000000000..2d68acd277 --- /dev/null +++ b/model/hardware/cpu-metrics.yaml @@ -0,0 +1,42 @@ +groups: + # CPU METRICS + - id: metric.hw.cpu + type: attribute_group + brief: > + Common attributes for CPU metrics + extends: hardware.attributes.common + attributes: + - ref: hw.model + requirement_level: recommended + - ref: hw.vendor + requirement_level: recommended + + + - id: metric.hw.cpu.speed + type: metric + metric_name: hw.cpu.speed + annotations: + code_generation: + metric_value_type: int + stability: development + brief: "CPU current frequency" + instrument: gauge + unit: "Hz" + extends: metric.hw.cpu + + # TODO: decide on metric name speed.limit is original + - id: metric.hw.cpu.speed.limit + type: metric + metric_name: hw.cpu.speed.limit + annotations: + code_generation: + metric_value_type: int + stability: development + brief: "CPU maximum frequency" + instrument: gauge + unit: "Hz" + extends: metric.hw.cpu + attributes: + - ref: hw.limit_type + examples: ["throttled", "max", "turbo"] + requirement_level: recommended diff --git a/model/hardware/disk-controller-metrics.yaml b/model/hardware/disk-controller-metrics.yaml new file mode 100644 index 0000000000..3856d63eef --- /dev/null +++ b/model/hardware/disk-controller-metrics.yaml @@ -0,0 +1,20 @@ +groups: + # DISK CONTROLLER METRICS + - id: metric.hw.disk_controller + type: attribute_group + brief: > + Common attributes for disk controller metrics + extends: hardware.attributes.common + attributes: + - ref: hw.bios_version + requirement_level: recommended + - ref: hw.driver_version + requirement_level: recommended + - ref: hw.firmware_version + requirement_level: recommended + - ref: hw.model + requirement_level: recommended + - ref: hw.serial_number + requirement_level: recommended + - ref: hw.vendor + requirement_level: recommended diff --git a/model/hardware/enclosure-metrics.yaml b/model/hardware/enclosure-metrics.yaml new file mode 100644 index 0000000000..234e50bb78 --- /dev/null +++ b/model/hardware/enclosure-metrics.yaml @@ -0,0 +1,18 @@ +groups: + # ENCLOSURE METRICS + - id: metric.hw.enclosure + type: attribute_group + brief: > + Common attributes for enclosure metrics + extends: hardware.attributes.common + attributes: + - ref: hw.bios_version + requirement_level: recommended + - ref: hw.model + requirement_level: recommended + - ref: hw.serial_number + requirement_level: recommended + - ref: hw.enclosure.type + requirement_level: recommended + - ref: hw.vendor + requirement_level: recommended diff --git a/model/hardware/fan-metrics.yaml b/model/hardware/fan-metrics.yaml new file mode 100644 index 0000000000..059eaf5050 --- /dev/null +++ b/model/hardware/fan-metrics.yaml @@ -0,0 +1,50 @@ +groups: + # FAN METRICS + - id: metric.hw.fan + type: attribute_group + brief: > + Common attributes for fan metrics + extends: hardware.attributes.common + attributes: + - ref: hw.sensor_location + requirement_level: recommended + + - id: metric.hw.fan.speed + type: metric + metric_name: hw.fan.speed + annotations: + code_generation: + metric_value_type: int + stability: development + brief: "Fan speed in revolutions per minute" + instrument: gauge + unit: "rpm" + extends: metric.hw.fan + + - id: metric.hw.fan.speed.limit + type: metric + metric_name: hw.fan.speed.limit + annotations: + code_generation: + metric_value_type: int + stability: development + brief: "Speed limit in rpm" + instrument: gauge + unit: "rpm" + extends: metric.hw.fan + attributes: + - ref: hw.limit_type + examples: ["low.critical", "low.degraded", "max"] + requirement_level: recommended + + - id: metric.hw.fan.speed_ratio + type: metric + metric_name: hw.fan.speed_ratio + annotations: + code_generation: + metric_value_type: double + stability: development + brief: "Fan speed expressed as a fraction of its maximum speed" + instrument: gauge + unit: "1" + extends: metric.hw.fan diff --git a/model/hardware/gpu-metrics.yaml b/model/hardware/gpu-metrics.yaml new file mode 100644 index 0000000000..ece017ccce --- /dev/null +++ b/model/hardware/gpu-metrics.yaml @@ -0,0 +1,86 @@ +groups: + # GPU METRICS + - id: metric.hw.gpu + type: attribute_group + brief: > + Common attributes for GPU metrics + extends: hardware.attributes.common + attributes: + - ref: hw.driver_version + requirement_level: recommended + - ref: hw.firmware_version + requirement_level: recommended + - ref: hw.model + requirement_level: recommended + - ref: hw.serial_number + requirement_level: recommended + - ref: hw.vendor + requirement_level: recommended + + - id: metric.hw.gpu.io + type: metric + metric_name: hw.gpu.io + annotations: + code_generation: + metric_value_type: int + stability: development + brief: "Received and transmitted bytes by the GPU" + instrument: counter + unit: "By" + extends: metric.hw.gpu + attributes: + - ref: network.io.direction + examples: ["receive", "transmit"] + requirement_level: required + + - id: metric.hw.gpu.memory.limit + type: metric + metric_name: hw.gpu.memory.limit + annotations: + code_generation: + metric_value_type: int + stability: development + brief: "Size of the GPU memory" + instrument: updowncounter + unit: "By" + extends: metric.hw.gpu + + - id: metric.hw.gpu.memory.utilization + type: metric + metric_name: hw.gpu.memory.utilization + annotations: + code_generation: + metric_value_type: double + stability: development + brief: "Fraction of GPU memory used" + instrument: gauge + unit: "1" + extends: metric.hw.gpu + + - id: metric.hw.gpu.memory.usage + type: metric + metric_name: hw.gpu.memory.usage + annotations: + code_generation: + metric_value_type: int + stability: development + brief: "GPU memory used" + instrument: updowncounter + unit: "By" + extends: metric.hw.gpu + + - id: metric.hw.gpu.utilization + type: metric + metric_name: hw.gpu.utilization + annotations: + code_generation: + metric_value_type: double + stability: development + brief: "Fraction of time spent in a specific task" + instrument: gauge + unit: "1" + extends: metric.hw.gpu + attributes: + - ref: hw.gpu.task + examples: ["decoder", "encoder", "general"] + requirement_level: recommended diff --git a/model/hardware/host-metrics.yaml b/model/hardware/host-metrics.yaml index 76af136c3d..171e8d9617 100644 --- a/model/hardware/host-metrics.yaml +++ b/model/hardware/host-metrics.yaml @@ -17,7 +17,7 @@ groups: metric_name: hw.host.energy annotations: code_generation: - metric_value_type: double + metric_value_type: int stability: development brief: "Total energy consumed by the entire physical host, in joules" instrument: counter diff --git a/model/hardware/logical-disk-metrics.yaml b/model/hardware/logical-disk-metrics.yaml new file mode 100644 index 0000000000..be381db2bd --- /dev/null +++ b/model/hardware/logical-disk-metrics.yaml @@ -0,0 +1,54 @@ +groups: + # LOGICAL DISK METRICS + - id: metric.hw.logical_disk + type: attribute_group + brief: > + Common attributes for logical disk metrics + extends: hardware.attributes.common + attributes: + - ref: hw.logical_disk.raid_level + requirement_level: recommended + + - id: metric.hw.logical_disk.limit + type: metric + metric_name: hw.logical_disk.limit + annotations: + code_generation: + metric_value_type: int + stability: development + brief: "Size of the logical disk" + instrument: updowncounter + unit: "By" + extends: metric.hw.logical_disk + + - id: metric.hw.logical_disk.usage + type: metric + metric_name: hw.logical_disk.usage + annotations: + code_generation: + metric_value_type: int + stability: development + brief: "Logical disk space usage" + instrument: updowncounter + unit: "By" + extends: metric.hw.logical_disk + attributes: + - ref: hw.logical_disk.state + examples: ["used", "free"] + requirement_level: required + + - id: metric.hw.logical_disk.utilization + type: metric + metric_name: hw.logical_disk.utilization + annotations: + code_generation: + metric_value_type: double + stability: development + brief: "Logical disk space utilization as a fraction" + instrument: gauge + unit: "1" + extends: metric.hw.logical_disk + attributes: + - ref: hw.logical_disk.state + examples: ["used", "free"] + requirement_level: required diff --git a/model/hardware/memory-metrics.yaml b/model/hardware/memory-metrics.yaml new file mode 100644 index 0000000000..8bfbc7a143 --- /dev/null +++ b/model/hardware/memory-metrics.yaml @@ -0,0 +1,28 @@ +groups: + # MEMORY METRICS + - id: metric.hw.memory + type: attribute_group + brief: > + Common attributes for memory module metrics + extends: hardware.attributes.common + attributes: + - ref: hw.model + requirement_level: recommended + - ref: hw.serial_number + requirement_level: recommended + - ref: hw.memory.type + requirement_level: recommended + - ref: hw.vendor + requirement_level: recommended + + - id: metric.hw.memory.size + type: metric + metric_name: hw.memory.size + annotations: + code_generation: + metric_value_type: int + stability: development + brief: "Size of the memory module" + instrument: updowncounter + unit: "By" + extends: metric.hw.memory diff --git a/model/hardware/network-metrics.yaml b/model/hardware/network-metrics.yaml new file mode 100644 index 0000000000..d9b8c1ff75 --- /dev/null +++ b/model/hardware/network-metrics.yaml @@ -0,0 +1,86 @@ +groups: + # NETWORK METRICS + - id: metric.hw.network + type: attribute_group + brief: > + Common attributes for network adapter metrics + extends: hardware.attributes.common + attributes: + - ref: hw.model + requirement_level: recommended + - ref: hw.network.logical_addresses + requirement_level: recommended + - ref: hw.network.physical_address + requirement_level: recommended + - ref: hw.serial_number + requirement_level: recommended + - ref: hw.vendor + requirement_level: recommended + + - id: metric.hw.network.bandwidth.limit + type: metric + metric_name: hw.network.bandwidth.limit + annotations: + code_generation: + metric_value_type: int + stability: development + brief: "Link speed" + instrument: updowncounter + unit: "By/s" + extends: metric.hw.network + + - id: metric.hw.network.bandwidth.utilization + type: metric + metric_name: hw.network.bandwidth.utilization + annotations: + code_generation: + metric_value_type: double + stability: development + brief: "Utilization of the network bandwidth as a fraction" + instrument: gauge + unit: "1" + extends: metric.hw.network + + - id: metric.hw.network.io + type: metric + metric_name: hw.network.io + annotations: + code_generation: + metric_value_type: int + stability: development + brief: "Received and transmitted network traffic in bytes" + instrument: counter + unit: "By" + extends: metric.hw.network + attributes: + - ref: network.io.direction + examples: ["receive", "transmit"] + requirement_level: required + + - id: metric.hw.network.packets + type: metric + metric_name: hw.network.packets + annotations: + code_generation: + metric_value_type: int + stability: development + brief: "Received and transmitted network traffic in packets (or frames)" + instrument: counter + unit: "{packet}" + extends: metric.hw.network + attributes: + - ref: network.io.direction + examples: ["receive", "transmit"] + requirement_level: required + + - id: metric.hw.network.up + type: metric + metric_name: hw.network.up + annotations: + code_generation: + metric_value_type: int + stability: development + brief: "Link status: `1` (up) or `0` (down)" + instrument: updowncounter + unit: "1" + extends: metric.hw.network diff --git a/model/hardware/physical-disk-metrics.yaml b/model/hardware/physical-disk-metrics.yaml new file mode 100644 index 0000000000..14ae166999 --- /dev/null +++ b/model/hardware/physical-disk-metrics.yaml @@ -0,0 +1,62 @@ +groups: + # PHYSICAL DISK METRICS + - id: metric.hw.physical_disk + type: attribute_group + brief: > + Common attributes for physical disk metrics + extends: hardware.attributes.common + attributes: + - ref: hw.firmware_version + requirement_level: recommended + - ref: hw.model + requirement_level: recommended + - ref: hw.serial_number + requirement_level: recommended + - ref: hw.physical_disk.type + requirement_level: recommended + - ref: hw.vendor + requirement_level: recommended + + - id: metric.hw.physical_disk.endurance_utilization + type: metric + metric_name: hw.physical_disk.endurance_utilization + annotations: + code_generation: + metric_value_type: double + stability: development + brief: "Endurance remaining for this SSD disk" + instrument: gauge + unit: "1" + extends: metric.hw.physical_disk + attributes: + - ref: hw.physical_disk.state + examples: ["remaining"] + requirement_level: required + + - id: metric.hw.physical_disk.size + type: metric + metric_name: hw.physical_disk.size + annotations: + code_generation: + metric_value_type: int + stability: development + brief: "Size of the disk" + instrument: updowncounter + unit: "By" + extends: metric.hw.physical_disk + + - id: metric.hw.physical_disk.smart + type: metric + metric_name: hw.physical_disk.smart + annotations: + code_generation: + metric_value_type: int + stability: development + brief: "Value of the corresponding [S.M.A.R.T.](https://wikipedia.org/wiki/S.M.A.R.T.) (Self-Monitoring, Analysis, and Reporting Technology) attribute" + instrument: gauge + unit: "1" + extends: metric.hw.physical_disk + attributes: + - ref: hw.physical_disk.smart_attribute + examples: ['Spin Retry Count', 'Seek Error Rate'] + requirement_level: recommended diff --git a/model/hardware/power-supply-metrics.yaml b/model/hardware/power-supply-metrics.yaml new file mode 100644 index 0000000000..7c1d1788c2 --- /dev/null +++ b/model/hardware/power-supply-metrics.yaml @@ -0,0 +1,54 @@ +groups: + # POWER SUPPLY METRICS + - id: metric.hw.power_supply + type: attribute_group + brief: > + Common attributes for power supply metrics + extends: hardware.attributes.common + attributes: + - ref: hw.model + requirement_level: recommended + - ref: hw.serial_number + requirement_level: recommended + - ref: hw.vendor + requirement_level: recommended + + - id: metric.hw.power_supply.limit + type: metric + metric_name: hw.power_supply.limit + annotations: + code_generation: + metric_value_type: int + stability: development + brief: "Maximum power output of the power supply" + instrument: updowncounter + unit: "W" + extends: metric.hw.power_supply + attributes: + - ref: hw.limit_type + examples: ["max", "critical", "throttled"] + requirement_level: recommended + + - id: metric.hw.power_supply.utilization + type: metric + metric_name: hw.power_supply.utilization + annotations: + code_generation: + metric_value_type: double + stability: development + brief: "Utilization of the power supply as a fraction of its maximum output" + instrument: gauge + unit: "1" + extends: metric.hw.power_supply + + - id: metric.hw.power_supply.usage + type: metric + metric_name: hw.power_supply.usage + annotations: + code_generation: + metric_value_type: double + stability: development + brief: "Current power output of the power supply" + instrument: updowncounter + unit: "W" + extends: metric.hw.power_supply diff --git a/model/hardware/registry.yaml b/model/hardware/registry.yaml index 48a6ad870a..789f4057e7 100644 --- a/model/hardware/registry.yaml +++ b/model/hardware/registry.yaml @@ -5,6 +5,7 @@ groups: brief: > Attributes for hardware. attributes: + # COMMON ATTRIBUTES FOR ALL - id: hw.id type: string stability: development @@ -92,10 +93,6 @@ groups: - id: hw.state type: members: - - id: ok - value: 'ok' - brief: "Ok" - stability: development - id: degraded value: 'degraded' brief: 'Degraded' @@ -104,6 +101,248 @@ groups: value: 'failed' brief: 'Failed' stability: development + - id: needs_cleaning + value: 'needs_cleaning' + brief: 'Needs Cleaning' + stability: development + - id: ok + value: 'ok' + brief: 'OK' + stability: development + - id: predicted_failure + value: 'predicted_failure' + brief: 'Predicted Failure' + stability: development stability: development brief: > The current state of the component + - id: hw.battery.state + type: + members: + - id: charging + value: 'charging' + brief: 'Charging' + stability: development + - id: discharging + value: 'discharging' + brief: 'Discharging' + stability: development + stability: development + brief: > + The current state of the battery + - id: hw.limit_type + type: + members: + - id: critical + value: 'critical' + brief: 'Critical' + stability: development + - id: degraded + value: 'degraded' + brief: 'Degraded' + stability: development + - id: high_critical + value: 'high.critical' + brief: 'High Critical' + stability: development + - id: high_degraded + value: 'high.degraded' + brief: 'High Degraded' + stability: development + - id: low_critical + value: 'low.critical' + brief: 'Low Critical' + stability: development + - id: low_degraded + value: 'low.degraded' + brief: 'Low Degraded' + stability: development + - id: max + value: 'max' + brief: 'Maximum' + stability: development + - id: throttled + value: 'throttled' + brief: 'Throttled' + stability: development + - id: turbo + value: 'turbo' + brief: 'Turbo' + stability: development + stability: development + brief: > + Type of limit for hardware components + + # COMMON ATTRIBUTES FOR SOME HARDWARE COMPONENTS + - id: hw.bios_version + type: string + stability: development + brief: > + BIOS version of the hardware component + examples: ['1.2.3'] + - id: hw.driver_version + type: string + stability: development + brief: > + Driver version for the hardware component + examples: ['10.2.1-3'] + - id: hw.firmware_version + type: string + stability: development + brief: > + Firmware version of the hardware component + examples: ['2.0.1'] + - id: hw.model + type: string + stability: development + brief: > + Descriptive model name of the hardware component + examples: ['PERC H740P', 'Intel(R) Core(TM) i7-10700K', 'Dell XPS 15 Battery'] + - id: hw.serial_number + type: string + stability: development + brief: > + Serial number of the hardware component + examples: ['CNFCP0123456789'] + - id: hw.vendor + type: string + stability: development + brief: > + Vendor name of the hardware component + examples: ['Dell', 'HP', 'Intel', 'AMD', 'LSI', 'Lenovo'] + - id: hw.sensor_location + type: string + stability: development + brief: > + Location of the sensor + examples: ['cpu0', 'ps1', 'INLET', 'CPU0_DIE', 'AMBIENT', 'MOTHERBOARD', 'PS0 V3_3', 'MAIN_12V', 'CPU_VCORE'] + + # BATTERY ATTRIBUTES + - id: hw.battery.chemistry + type: string + stability: development + brief: > + Battery [chemistry](https://schemas.dmtf.org/wbem/cim-html/2.31.0/CIM_Battery.html), e.g. Lithium-Ion, Nickel-Cadmium, etc. + examples: ['Li-ion', 'NiMH'] + - id: hw.battery.capacity + type: string + stability: development + brief: > + Design capacity in Watts-hours or Amper-hours + examples: ['9.3Ah', '50Wh'] + + # ENCLOSURE ATTRIBUTES + - id: hw.enclosure.type + type: string + stability: development + brief: > + Type of the enclosure (useful for modular systems) + examples: ['Computer', 'Storage', 'Switch'] + + # GPU ATTRIBUTES + - id: hw.gpu.task + type: + members: + - id: decoder + value: 'decoder' + brief: "Decoder" + stability: development + - id: encoder + value: 'encoder' + brief: 'Encoder' + stability: development + - id: general + value: 'general' + brief: 'General' + stability: development + stability: development + brief: > + Type of task the GPU is performing + + # LOGICAL DISK ATTRIBUTES + - id: hw.logical_disk.raid_level + type: string + stability: development + brief: > + RAID Level of the logical disk + examples: ['RAID0+1', 'RAID5', 'RAID10'] + - id: hw.logical_disk.state + type: + members: + - id: used + value: 'used' + brief: "Used" + stability: development + - id: free + value: 'free' + brief: 'Free' + stability: development + stability: development + brief: > + State of the logical disk space usage + + # MEMORY ATTRIBUTES + - id: hw.memory.type + type: string + stability: development + brief: > + Type of the memory module + examples: ['DDR4', 'DDR5', 'LPDDR5'] + + # NETWORK ATTRIBUTES + - id: hw.network.logical_addresses + type: string[] + stability: development + brief: > + Logical addresses of the adapter (e.g. IP address, or WWPN) + examples: [['172.16.8.21', '57.11.193.42']] + - id: hw.network.physical_address + type: string + stability: development + brief: > + Physical address of the adapter (e.g. MAC address, or WWNN) + examples: ['00-90-F5-E9-7B-36'] + + # PHYSICAL DISK ATTRIBUTES + - id: hw.physical_disk.type + type: string + stability: development + brief: > + Type of the physical disk + examples: ['HDD', 'SSD', '10K'] + - id: hw.physical_disk.state + type: + members: + - id: remaining + value: 'remaining' + brief: "Remaining" + stability: development + stability: development + brief: > + State of the physical disk endurance utilization + - id: hw.physical_disk.smart_attribute + type: string + stability: development + brief: > + [S.M.A.R.T.](https://wikipedia.org/wiki/S.M.A.R.T.) (Self-Monitoring, Analysis, and Reporting Technology) attribute of the physical disk + examples: ['Spin Retry Count', 'Seek Error Rate', 'Raw Read Error Rate'] + + # TAPE DRIVE ATTRIBUTES + - id: hw.tape_drive.operation_type + type: + members: + - id: mount + value: 'mount' + brief: "Mount" + stability: development + - id: unmount + value: 'unmount' + brief: 'Unmount' + stability: development + - id: clean + value: 'clean' + brief: 'Clean' + stability: development + stability: development + brief: > + Type of tape drive operation diff --git a/model/hardware/tape-drive-metrics.yaml b/model/hardware/tape-drive-metrics.yaml new file mode 100644 index 0000000000..ef339ccc8b --- /dev/null +++ b/model/hardware/tape-drive-metrics.yaml @@ -0,0 +1,30 @@ +groups: + # TAPE DRIVE METRICS + - id: metric.hw.tape_drive + type: attribute_group + brief: > + Common attributes for tape drive metrics + extends: hardware.attributes.common + attributes: + - ref: hw.model + requirement_level: recommended + - ref: hw.serial_number + requirement_level: recommended + - ref: hw.vendor + requirement_level: recommended + + - id: metric.hw.tape_drive.operations + type: metric + metric_name: hw.tape_drive.operations + annotations: + code_generation: + metric_value_type: int + stability: development + brief: "Operations performed by the tape drive" + instrument: counter + unit: "{operation}" + extends: metric.hw.tape_drive + attributes: + - ref: hw.tape_drive.operation_type + examples: ["mount", "unmount", "clean"] + requirement_level: recommended diff --git a/model/hardware/temperature-metrics.yaml b/model/hardware/temperature-metrics.yaml new file mode 100644 index 0000000000..f3cb97bcc0 --- /dev/null +++ b/model/hardware/temperature-metrics.yaml @@ -0,0 +1,38 @@ +groups: + # TEMPERATURE METRICS + - id: metric.hw.temperature.common + type: attribute_group + brief: > + Common attributes for temperature metrics + extends: hardware.attributes.common + attributes: + - ref: hw.sensor_location + requirement_level: recommended + + - id: metric.hw.temperature + type: metric + metric_name: hw.temperature + annotations: + code_generation: + metric_value_type: double + stability: development + brief: "Temperature in degrees Celsius" + instrument: gauge + unit: "Cel" + extends: metric.hw.temperature.common + + - id: metric.hw.temperature.limit + type: metric + metric_name: hw.temperature.limit + annotations: + code_generation: + metric_value_type: double + stability: development + brief: "Temperature limit in degrees Celsius" + instrument: gauge + unit: "Cel" + extends: metric.hw.temperature.common + attributes: + - ref: hw.limit_type + examples: ["low.critical", "low.degraded", "high.degraded", "high.critical"] + requirement_level: recommended diff --git a/model/hardware/voltage-metrics.yaml b/model/hardware/voltage-metrics.yaml new file mode 100644 index 0000000000..61bb871c2a --- /dev/null +++ b/model/hardware/voltage-metrics.yaml @@ -0,0 +1,50 @@ +groups: + # VOLTAGE METRICS + - id: metric.hw.voltage.common + type: attribute_group + brief: > + Common attributes for voltage metrics + extends: hardware.attributes.common + attributes: + - ref: hw.sensor_location + requirement_level: recommended + + - id: metric.hw.voltage + type: metric + metric_name: hw.voltage + annotations: + code_generation: + metric_value_type: double + stability: development + brief: "Voltage measured by the sensor" + instrument: gauge + unit: "V" + extends: metric.hw.voltage.common + + - id: metric.hw.voltage.limit + type: metric + metric_name: hw.voltage.limit + annotations: + code_generation: + metric_value_type: double + stability: development + brief: "Voltage limit in Volts" + instrument: gauge + unit: "V" + extends: metric.hw.voltage.common + attributes: + - ref: hw.limit_type + examples: ["low.critical", "low.degraded", "high.degraded", "high.critical"] + requirement_level: recommended + + - id: metric.hw.voltage.nominal + type: metric + metric_name: hw.voltage.nominal + annotations: + code_generation: + metric_value_type: double + stability: development + brief: "Nominal (expected) voltage" + instrument: gauge + unit: "V" + extends: metric.hw.voltage.common