# Semantic Conventions for Container Metrics **Status**: [Experimental][DocumentStatus] ## Container Metrics This document describes instruments and attributes for common container level metrics in OpenTelemetry. These metrics are collected from technology-specific, well-defined APIs (e.g. Kubelet's API or container runtimes). ### Metric: `container.cpu.time` This metric is [opt-in][MetricOptIn]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | | `container.cpu.time` | Counter | `s` | Total CPU time consumed [1] |  | **[1]:** Total CPU time consumed by the specific container on all available CPU cores | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`cpu.mode`](/docs/attributes-registry/cpu.md) | string | The CPU mode for this data point. A container's CPU metric SHOULD be characterized _either_ by data points with no `mode` labels, _or only_ data points with `mode` labels. [1] | `user`; `system` | `Conditionally Required` [2] |  | **[1] `cpu.mode`:** Following states SHOULD be used: `user`, `system`, `kernel` **[2] `cpu.mode`:** Required if mode is available, i.e. metrics coming from the Docker Stats API. `cpu.mode` 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 | |---|---|---| | `idle` | idle |  | | `interrupt` | interrupt |  | | `iowait` | iowait |  | | `kernel` | kernel |  | | `nice` | nice |  | | `steal` | steal |  | | `system` | system |  | | `user` | user |  | ### Metric: `container.cpu.usage` This metric is [opt-in][MetricOptIn]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | | `container.cpu.usage` | Gauge | `{cpu}` | Container's CPU usage, measured in cpus. Range from 0 to the number of allocatable CPUs [1] |  | **[1]:** CPU usage of the specific container on all available CPU cores, averaged over the sample window | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`cpu.mode`](/docs/attributes-registry/cpu.md) | string | The CPU mode for this data point. A container's CPU metric SHOULD be characterized _either_ by data points with no `mode` labels, _or only_ data points with `mode` labels. [1] | `user`; `system` | `Conditionally Required` [2] |  | **[1] `cpu.mode`:** Following states SHOULD be used: `user`, `system`, `kernel` **[2] `cpu.mode`:** Required if mode is available, i.e. metrics coming from the Docker Stats API. `cpu.mode` 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 | |---|---|---| | `idle` | idle |  | | `interrupt` | interrupt |  | | `iowait` | iowait |  | | `kernel` | kernel |  | | `nice` | nice |  | | `steal` | steal |  | | `system` | system |  | | `user` | user |  | ### Metric: `container.memory.usage` This metric is [opt-in][MetricOptIn]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | | `container.memory.usage` | Counter | `By` | Memory usage of the container. [1] |  | **[1]:** Memory usage of the container. ### Metric: `container.disk.io` This metric is [opt-in][MetricOptIn]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | | `container.disk.io` | Counter | `By` | Disk bytes for the container. [1] |  | **[1]:** The total number of bytes read/written successfully (aggregated from all disks). | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`disk.io.direction`](/docs/attributes-registry/disk.md) | string | The disk IO operation direction. | `read` | `Recommended` |  | | [`system.device`](/docs/attributes-registry/system.md) | string | The device identifier | `(identifier)` | `Recommended` |  | `disk.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 | |---|---|---| | `read` | read |  | | `write` | write |  | ### Metric: `container.network.io` This metric is [opt-in][MetricOptIn]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | | `container.network.io` | Counter | `By` | Network bytes for the container. [1] |  | **[1]:** The number of bytes sent/received on all network interfaces by the container. | 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 [MetricOptIn]: /docs/general/metric-requirement-level.md#opt-in