# Semantic conventions for container metrics LLMS index: [llms.txt](/llms.txt) --- **Status**: [Development][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.uptime`](#metric-containeruptime) - [Metric: `container.cpu.time`](#metric-containercputime) - [Metric: `container.cpu.usage`](#metric-containercpuusage) - [Metric: `container.memory.usage`](#metric-containermemoryusage) - [Metric: `container.memory.available`](#metric-containermemoryavailable) - [Metric: `container.memory.rss`](#metric-containermemoryrss) - [Metric: `container.memory.working_set`](#metric-containermemoryworking_set) - [Metric: `container.memory.paging.faults`](#metric-containermemorypagingfaults) - [Metric: `container.disk.io`](#metric-containerdiskio) - [Metric: `container.network.io`](#metric-containernetworkio) - [Metric: `container.filesystem.available`](#metric-containerfilesystemavailable) - [Metric: `container.filesystem.capacity`](#metric-containerfilesystemcapacity) - [Metric: `container.filesystem.usage`](#metric-containerfilesystemusage) ### Metric: `container.uptime` This metric is [recommended][MetricRecommended]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | | -------- | --------------- | ----------- | -------------- | --------- | ------ | | `container.uptime` | Gauge | `s` | The time the container has been running. [1] | ![Development](https://img.shields.io/badge/-development-blue) | [`container`](/docs/specs/semconv/registry/entities/container.md#container) | **[1]:** Instrumentations SHOULD use a gauge with type `double` and measure uptime in seconds as a floating point number with the highest precision available. The actual accuracy would depend on the instrumentation and operating system. ### Metric: `container.cpu.time` This metric is [recommended][MetricRecommended]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | | -------- | --------------- | ----------- | -------------- | --------- | ------ | | `container.cpu.time` | Counter | `s` | CPU time consumed. [1] | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | [`container`](/docs/specs/semconv/registry/entities/container.md#container) | **[1]:** CPU time consumed by the specific container on all available CPU cores **Attributes:** | Key | Stability | [Requirement Level](/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values | | --- | --- | --- | --- | --- | --- | | [`cpu.mode`](/docs/specs/semconv/registry/attributes/cpu.md) | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | `Conditionally Required` [1] | 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. [2] | `user`; `system` | **[1] `cpu.mode`:** Required if mode is available, i.e. metrics coming from the Docker Stats API, containerd stats or cAdvisor. **[2] `cpu.mode`:** Following modes SHOULD be used for containers if available: `user`, `system`. In implementations like [`opencontainers/cgroup`](https://pkg.go.dev/github.com/opencontainers/cgroups@v0.0.6#CpuUsage), [Moby/Docker](https://pkg.go.dev/github.com/Moby/Moby@v28.5.2+incompatible/api/types/container#CPUUsage) or [cAdvisor](https://pkg.go.dev/github.com/google/cadvisor@v0.56.2/info/v1#CpuUsage), the respective states are retrieved from the cgroup stats directly. In cgroup v1 the user/system modes come from the [cpuacct.stat](https://www.kernel.org/doc/html/latest/admin-guide/cgroup-v1/cpuacct.html#cpu-accounting-controller) file and the `user`/`system` stats respectively. In cgroup v2 the user/system modes come from the [cpu.stat](https://docs.kernel.org/admin-guide/cgroup-v2.html#cpu-interface-files) file and the `user_usec`/`system_usec` stats respectively. Kubernetes only exposes the total CPU time ([cpu.stat.usage_usec](https://docs.kernel.org/admin-guide/cgroup-v2.html#cpu-interface-files)) through Kubelet's stats API, hence the metric should be reported without the mode attribute implying it is the total of all modes. In pure container environments the CPU's mode is usually available and cpu.mode should be reported. In that case summarising the CPU time over the different modes gives the total CPU time. --- `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 | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | `interrupt` | Interrupt | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | `iowait` | IO Wait | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | `nice` | Nice | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | `steal` | Steal | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | `system` | System | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | `user` | User | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | ### Metric: `container.cpu.usage` This metric is [opt-in][MetricOptIn]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | | -------- | --------------- | ----------- | -------------- | --------- | ------ | | `container.cpu.usage` | Gauge | `{cpu}` | Container's CPU usage, measured in cpus. Range from 0 to the number of allocatable CPUs. [1] | ![Development](https://img.shields.io/badge/-development-blue) | [`container`](/docs/specs/semconv/registry/entities/container.md#container) | **[1]:** CPU usage of the specific container on all available CPU cores, averaged over the sample window **Attributes:** | Key | Stability | [Requirement Level](/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values | | --- | --- | --- | --- | --- | --- | | [`cpu.mode`](/docs/specs/semconv/registry/attributes/cpu.md) | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | `Conditionally Required` [1] | 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. [2] | `user`; `system` | **[1] `cpu.mode`:** Required if mode is available, i.e. metrics coming from the Docker Stats API, containerd stats or cAdvisor. **[2] `cpu.mode`:** Following modes SHOULD be used for containers if available: `user`, `system`. --- `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 | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | `interrupt` | Interrupt | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | `iowait` | IO Wait | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | `nice` | Nice | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | `steal` | Steal | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | `system` | System | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | `user` | User | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | ### Metric: `container.memory.usage` This metric is [opt-in][MetricOptIn]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | | -------- | --------------- | ----------- | -------------- | --------- | ------ | | `container.memory.usage` | Counter | `By` | Memory usage of the container. [1] | ![Development](https://img.shields.io/badge/-development-blue) | [`container`](/docs/specs/semconv/registry/entities/container.md#container) | **[1]:** Memory usage of the container. ### Metric: `container.memory.available` This metric is [opt-in][MetricOptIn]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | | -------- | --------------- | ----------- | -------------- | --------- | ------ | | `container.memory.available` | UpDownCounter | `By` | Container memory available. [1] | ![Development](https://img.shields.io/badge/-development-blue) | [`container`](/docs/specs/semconv/registry/entities/container.md#container) | **[1]:** Available memory for use. This is defined as the memory limit - workingSetBytes. If memory limit is undefined, the available bytes is omitted. In general, this metric can be derived from [cadvisor](https://github.com/google/cadvisor/blob/v0.53.0/docs/storage/prometheus.md#prometheus-container-metrics) and by subtracting the `container_memory_working_set_bytes` metric from the `container_spec_memory_limit_bytes` metric. In K8s, this metric is derived from the [MemoryStats.AvailableBytes](https://pkg.go.dev/k8s.io/kubelet@v0.34.0/pkg/apis/stats/v1alpha1#MemoryStats) field of the [PodStats.Memory](https://pkg.go.dev/k8s.io/kubelet@v0.34.0/pkg/apis/stats/v1alpha1#PodStats) of the Kubelet's stats API. ### Metric: `container.memory.rss` This metric is [opt-in][MetricOptIn]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | | -------- | --------------- | ----------- | -------------- | --------- | ------ | | `container.memory.rss` | UpDownCounter | `By` | Container memory RSS. [1] | ![Development](https://img.shields.io/badge/-development-blue) | [`container`](/docs/specs/semconv/registry/entities/container.md#container) | **[1]:** In general, this metric can be derived from [cadvisor](https://github.com/google/cadvisor/blob/v0.53.0/docs/storage/prometheus.md#prometheus-container-metrics) and specifically the `container_memory_rss` metric. In K8s, this metric is derived from the [MemoryStats.RSSBytes](https://pkg.go.dev/k8s.io/kubelet@v0.34.0/pkg/apis/stats/v1alpha1#MemoryStats) field of the [PodStats.Memory](https://pkg.go.dev/k8s.io/kubelet@v0.34.0/pkg/apis/stats/v1alpha1#PodStats) of the Kubelet's stats API. ### Metric: `container.memory.working_set` This metric is [opt-in][MetricOptIn]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | | -------- | --------------- | ----------- | -------------- | --------- | ------ | | `container.memory.working_set` | UpDownCounter | `By` | Container memory working set. [1] | ![Development](https://img.shields.io/badge/-development-blue) | [`container`](/docs/specs/semconv/registry/entities/container.md#container) | **[1]:** In general, this metric can be derived from [cadvisor](https://github.com/google/cadvisor/blob/v0.53.0/docs/storage/prometheus.md#prometheus-container-metrics) and specifically the `container_memory_working_set_bytes` metric. In K8s, this metric is derived from the [MemoryStats.WorkingSetBytes](https://pkg.go.dev/k8s.io/kubelet@v0.34.0/pkg/apis/stats/v1alpha1#MemoryStats) field of the [PodStats.Memory](https://pkg.go.dev/k8s.io/kubelet@v0.34.0/pkg/apis/stats/v1alpha1#PodStats) of the Kubelet's stats API. ### Metric: `container.memory.paging.faults` This metric is [opt-in][MetricOptIn]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | | -------- | --------------- | ----------- | -------------- | --------- | ------ | | `container.memory.paging.faults` | Counter | `{fault}` | Container memory paging faults. [1] | ![Development](https://img.shields.io/badge/-development-blue) | [`container`](/docs/specs/semconv/registry/entities/container.md#container) | **[1]:** In general, this metric can be derived from [cadvisor](https://github.com/google/cadvisor/blob/v0.53.0/docs/storage/prometheus.md#prometheus-container-metrics) and specifically the `container_memory_failures_total{failure_type=pgfault, scope=container}` and `container_memory_failures_total{failure_type=pgmajfault, scope=container}`metric. In K8s, this metric is derived from the [MemoryStats.PageFaults](https://pkg.go.dev/k8s.io/kubelet@v0.34.0/pkg/apis/stats/v1alpha1#MemoryStats) and [MemoryStats.MajorPageFaults](https://pkg.go.dev/k8s.io/kubelet@v0.34.0/pkg/apis/stats/v1alpha1#MemoryStats) field of the [PodStats.Memory](https://pkg.go.dev/k8s.io/kubelet@v0.34.0/pkg/apis/stats/v1alpha1#PodStats) of the Kubelet's stats API. **Attributes:** | Key | Stability | [Requirement Level](/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values | | --- | --- | --- | --- | --- | --- | | [`system.paging.fault.type`](/docs/specs/semconv/registry/attributes/system.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The paging fault type | `minor` | --- `system.paging.fault.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 | | --- | --- | --- | | `major` | major | ![Development](https://img.shields.io/badge/-development-blue) | | `minor` | minor | ![Development](https://img.shields.io/badge/-development-blue) | ### Metric: `container.disk.io` This metric is [opt-in][MetricOptIn]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | | -------- | --------------- | ----------- | -------------- | --------- | ------ | | `container.disk.io` | Counter | `By` | Disk bytes for the container. [1] | ![Development](https://img.shields.io/badge/-development-blue) | [`container`](/docs/specs/semconv/registry/entities/container.md#container) | **[1]:** The total number of bytes read/written successfully (aggregated from all disks). **Attributes:** | Key | Stability | [Requirement Level](/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values | | --- | --- | --- | --- | --- | --- | | [`disk.io.direction`](/docs/specs/semconv/registry/attributes/disk.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The disk IO operation direction. | `read` | | [`system.device`](/docs/specs/semconv/registry/attributes/system.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The device identifier | `(identifier)` | --- `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 | ![Development](https://img.shields.io/badge/-development-blue) | | `write` | write | ![Development](https://img.shields.io/badge/-development-blue) | ### Metric: `container.network.io` This metric is [opt-in][MetricOptIn]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | | -------- | --------------- | ----------- | -------------- | --------- | ------ | | `container.network.io` | Counter | `By` | Network bytes for the container. [1] | ![Development](https://img.shields.io/badge/-development-blue) | [`container`](/docs/specs/semconv/registry/entities/container.md#container) | **[1]:** The number of bytes sent/received on all network interfaces by the container. **Attributes:** | Key | Stability | [Requirement Level](/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values | | --- | --- | --- | --- | --- | --- | | [`network.interface.name`](/docs/specs/semconv/registry/attributes/network.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The network interface name. | `lo`; `eth0` | | [`network.io.direction`](/docs/specs/semconv/registry/attributes/network.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The network IO operation direction. | `transmit` | --- `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: `container.filesystem.available` This metric is [recommended][MetricRecommended]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | | -------- | --------------- | ----------- | -------------- | --------- | ------ | | `container.filesystem.available` | UpDownCounter | `By` | Container filesystem available bytes. [1] | ![Development](https://img.shields.io/badge/-development-blue) | [`container`](/docs/specs/semconv/registry/entities/container.md#container) | **[1]:** In K8s, this metric is derived from the [FsStats.AvailableBytes](https://pkg.go.dev/k8s.io/kubelet@v0.33.0/pkg/apis/stats/v1alpha1#FsStats) field of the [ContainerStats.Rootfs](https://pkg.go.dev/k8s.io/kubelet@v0.33.0/pkg/apis/stats/v1alpha1#ContainerStats) of the Kubelet's stats API. ### Metric: `container.filesystem.capacity` This metric is [recommended][MetricRecommended]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | | -------- | --------------- | ----------- | -------------- | --------- | ------ | | `container.filesystem.capacity` | UpDownCounter | `By` | Container filesystem capacity. [1] | ![Development](https://img.shields.io/badge/-development-blue) | [`container`](/docs/specs/semconv/registry/entities/container.md#container) | **[1]:** In K8s, this metric is derived from the [FsStats.CapacityBytes](https://pkg.go.dev/k8s.io/kubelet@v0.33.0/pkg/apis/stats/v1alpha1#FsStats) field of the [ContainerStats.Rootfs](https://pkg.go.dev/k8s.io/kubelet@v0.33.0/pkg/apis/stats/v1alpha1#ContainerStats) of the Kubelet's stats API. ### Metric: `container.filesystem.usage` This metric is [recommended][MetricRecommended]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | | -------- | --------------- | ----------- | -------------- | --------- | ------ | | `container.filesystem.usage` | UpDownCounter | `By` | Container filesystem usage. [1] | ![Development](https://img.shields.io/badge/-development-blue) | [`container`](/docs/specs/semconv/registry/entities/container.md#container) | **[1]:** This may not equal capacity - available. In K8s, this metric is derived from the [FsStats.UsedBytes](https://pkg.go.dev/k8s.io/kubelet@v0.33.0/pkg/apis/stats/v1alpha1#FsStats) field of the [ContainerStats.Rootfs](https://pkg.go.dev/k8s.io/kubelet@v0.33.0/pkg/apis/stats/v1alpha1#ContainerStats) of the Kubelet's stats API. [DocumentStatus]: /docs/specs/otel/document-status [MetricOptIn]: /docs/specs/semconv/general/metric-requirement-level.md#opt-in [MetricRecommended]: /docs/specs/semconv/general/metric-requirement-level.md#recommended