# Semantic Conventions for Kubernetes Metrics **Status**: [Experimental][DocumentStatus] ## K8s Metrics This document describes instruments and attributes for common K8s level metrics in OpenTelemetry. These metrics are collected from technology-specific, well-defined APIs (e.g. Kubelet's API). Metrics in `k8s.` instruments SHOULD be attached to a [K8s Resource](/docs/resource/k8s.md) and therefore inherit its attributes, like `k8s.pod.name` and `k8s.pod.uid`. ### Metric: `k8s.pod.cpu.time` This metric is [recommended][MetricRecommended]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | | `k8s.pod.cpu.time` | Counter | `s` | Total CPU time consumed [1] |  | **[1]:** Total CPU time consumed by the specific Pod on all available CPU cores ### Metric: `k8s.pod.cpu.usage` This metric is [recommended][MetricRecommended]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | | `k8s.pod.cpu.usage` | Gauge | `{cpu}` | Pod's CPU usage, measured in cpus. Range from 0 to the number of allocatable CPUs [1] |  | **[1]:** CPU usage of the specific Pod on all available CPU cores, averaged over the sample window ### Metric: `k8s.pod.memory.usage` This metric is [recommended][MetricRecommended]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | | `k8s.pod.memory.usage` | Gauge | `By` | Memory usage of the Pod [1] |  | **[1]:** Total memory usage of the Pod ### Metric: `k8s.pod.network.io` This metric is [recommended][MetricRecommended]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | | `k8s.pod.network.io` | Counter | `By` | Network bytes for the Pod |  | | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`network.interface.name`](/docs/attributes-registry/network.md) | string | The network interface name. | `lo`; `eth0` | `Recommended` |  | | [`network.io.direction`](/docs/attributes-registry/network.md) | string | The network IO operation direction. | `transmit` | `Recommended` |  | --- `network.io.direction` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. | Value | Description | Stability | |---|---|---| | `receive` | receive |  | | `transmit` | transmit |  | ### Metric: `k8s.pod.network.errors` This metric is [recommended][MetricRecommended]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | | `k8s.pod.network.errors` | Counter | `{error}` | Pod network errors |  | | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`network.interface.name`](/docs/attributes-registry/network.md) | string | The network interface name. | `lo`; `eth0` | `Recommended` |  | | [`network.io.direction`](/docs/attributes-registry/network.md) | string | The network IO operation direction. | `transmit` | `Recommended` |  | --- `network.io.direction` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. | Value | Description | Stability | |---|---|---| | `receive` | receive |  | | `transmit` | transmit |  | ### Metric: `k8s.node.cpu.time` This metric is [recommended][MetricRecommended]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | | `k8s.node.cpu.time` | Counter | `s` | Total CPU time consumed [1] |  | **[1]:** Total CPU time consumed by the specific Node on all available CPU cores ### Metric: `k8s.node.cpu.usage` This metric is [recommended][MetricRecommended]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | | `k8s.node.cpu.usage` | Gauge | `{cpu}` | Node's CPU usage, measured in cpus. Range from 0 to the number of allocatable CPUs [1] |  | **[1]:** CPU usage of the specific Node on all available CPU cores, averaged over the sample window ### Metric: `k8s.node.memory.usage` This metric is [recommended][MetricRecommended]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | | `k8s.node.memory.usage` | Gauge | `By` | Memory usage of the Node [1] |  | **[1]:** Total memory usage of the Node ### Metric: `k8s.node.network.io` This metric is [recommended][MetricRecommended]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | | `k8s.node.network.io` | Counter | `By` | Network bytes for the Node |  | | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`network.interface.name`](/docs/attributes-registry/network.md) | string | The network interface name. | `lo`; `eth0` | `Recommended` |  | | [`network.io.direction`](/docs/attributes-registry/network.md) | string | The network IO operation direction. | `transmit` | `Recommended` |  | --- `network.io.direction` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. | Value | Description | Stability | |---|---|---| | `receive` | receive |  | | `transmit` | transmit |  | ### Metric: `k8s.node.network.errors` This metric is [recommended][MetricRecommended]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | | `k8s.node.network.errors` | Counter | `{error}` | Node network errors |  | | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`network.interface.name`](/docs/attributes-registry/network.md) | string | The network interface name. | `lo`; `eth0` | `Recommended` |  | | [`network.io.direction`](/docs/attributes-registry/network.md) | string | The network IO operation direction. | `transmit` | `Recommended` |  | --- `network.io.direction` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. | Value | Description | Stability | |---|---|---| | `receive` | receive |  | | `transmit` | transmit |  | [DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status [MetricRecommended]: /docs/general/metric-requirement-level.md#recommended