# Semantic conventions for container metrics Site [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.paging.faults`](#metric-containerpagingfaults) - [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] | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | [`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. In K8s environments, this metric can be derived from Kubelet's stats API and specifically from the [ContainerStats.StartTime](https://github.com/kubernetes/kubelet/blob/v0.35.2/pkg/apis/stats/v1alpha1/types.go#L161) field, where `StartTime` represents the container creation time as [noted in the Kubelet source](https://github.com/kubernetes/kubernetes/blob/v1.36.3/pkg/kubelet/stats/cri_stats_provider.go#L776). This value resets on every container restart and aligns with [ContainerStateRunning.startedAt](https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/pod-v1/#ContainerStateRunning) from the K8s API. ### Metric: `container.cpu.time` This metric is [recommended][MetricRecommended]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | | -------- | --------------- | ----------- | -------------- | --------- | ------ | | `container.cpu.time` | Counter | `s` | Total 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` [(see more)](#cpu-mode-values) | **[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] | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | [`container`](/docs/specs/semconv/registry/entities/container.md#container) | **[1]:** CPU usage of the specific container on all available CPU cores. It is calculated as the change in cumulative CPU time (container.cpu.time) over a measurement interval, divided by the elapsed time: usageCores = (cpuTimeEnd - cpuTimeStart) / elapsedSeconds **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` [(see more)](#cpu-mode-values) | **[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` | UpDownCounter | `By` | Memory usage of the container. [1] | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | [`container`](/docs/specs/semconv/registry/entities/container.md#container) | **[1]:** Current memory usage, including all memory regardless of when it was accessed. 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_usage_bytes` metric. In K8s, this metric is derived from the [MemoryStats.UsageBytes](https://pkg.go.dev/k8s.io/kubelet@v0.34.0/pkg/apis/stats/v1alpha1#MemoryStats) field of the [ContainerStats.Memory](https://pkg.go.dev/k8s.io/kubelet@v0.34.0/pkg/apis/stats/v1alpha1#ContainerStats) of the Kubelet's stats API. ### 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] | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | [`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 [ContainerStats.Memory](https://pkg.go.dev/k8s.io/kubelet@v0.34.0/pkg/apis/stats/v1alpha1#ContainerStats) 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] | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | [`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 [ContainerStats.Memory](https://pkg.go.dev/k8s.io/kubelet@v0.34.0/pkg/apis/stats/v1alpha1#ContainerStats) 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] | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | [`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. When derived from cAdvisor on Linux, the working set is calculated by excluding inactive file-backed memory from memory usage (`inactive_file` on cgroup v2, `total_inactive_file` on cgroup v1), so active file-backed memory remains included. 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 [ContainerStats.Memory](https://pkg.go.dev/k8s.io/kubelet@v0.34.0/pkg/apis/stats/v1alpha1#ContainerStats) of the Kubelet's stats API. ### Metric: `container.paging.faults` This metric is [opt-in][MetricOptIn]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | | -------- | --------------- | ----------- | -------------- | --------- | ------ | | `container.paging.faults` | Counter | `{fault}` | Container memory paging faults. [1] | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | [`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). The `container_memory_failures_total{failure_type=pgfault, scope=container}` counter reports the total page faults (minor + major), while `container_memory_failures_total{failure_type=pgmajfault, scope=container}` reports only major faults. The minor page faults MUST be derived as the difference between the two. 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) fields of the [ContainerStats.Memory](https://pkg.go.dev/k8s.io/kubelet@v0.34.0/pkg/apis/stats/v1alpha1#ContainerStats) of the Kubelet's stats API. `MemoryStats.PageFaults` reports the total number of page faults (equivalent to `pgfault` in the cgroup `memory.stat`), with minor and major combined. The minor page faults MUST therefore be derived as `MemoryStats.PageFaults - MemoryStats.MajorPageFaults`, so that summing the metric over `system.paging.fault.type` yields the total number of page faults. **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) | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | `Recommended` | string | The paging fault type | `minor` [(see more)](#system-paging-fault-type-values) | --- `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 | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | `minor` | minor | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | ### 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) | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | `Recommended` | string | The disk IO operation direction. | `read` [(see more)](#disk-io-direction-values) | | [`system.device.name`](/docs/specs/semconv/registry/attributes/system.md) | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | `Recommended` | string | The OS level identifier for a device, such as disk, partition or network interface. | `/dev/sda`; `eth0`; `\network-drive` | --- `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 | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | `write` | write | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | ### 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) | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | `Recommended` | string | The network interface name. | `lo`; `eth0` | | [`network.io.direction`](/docs/specs/semconv/registry/attributes/network.md) | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | `Recommended` | string | The direction of traffic from the perspective of the observing host's physical or virtual network interface. It should not be used to represent the logical direction of a stateful connection or network flow. | `transmit` [(see more)](#network-io-direction-values) | --- `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 | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | `transmit` | transmit | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | ### 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] | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | [`container`](/docs/specs/semconv/registry/entities/container.md#container) | **[1]:** Available filesystem space for the container's `rootfs`. In K8s, this metric is derived from the [FsStats.AvailableBytes](https://pkg.go.dev/k8s.io/kubelet@v0.34.0/pkg/apis/stats/v1alpha1#FsStats) field of the [ContainerStats.Rootfs](https://pkg.go.dev/k8s.io/kubelet@v0.34.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] | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | [`container`](/docs/specs/semconv/registry/entities/container.md#container) | **[1]:** Total filesystem capacity for the container's `rootfs`. 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_fs_limit_bytes` metric for the container's `rootfs` device. In K8s, this metric is derived from the [FsStats.CapacityBytes](https://pkg.go.dev/k8s.io/kubelet@v0.34.0/pkg/apis/stats/v1alpha1#FsStats) field of the [ContainerStats.Rootfs](https://pkg.go.dev/k8s.io/kubelet@v0.34.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] | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | [`container`](/docs/specs/semconv/registry/entities/container.md#container) | **[1]:** Filesystem space used by the container's `rootfs`. 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_fs_usage_bytes` metric for the container's `rootfs` device. In K8s, this metric is derived from the [FsStats.UsedBytes](https://pkg.go.dev/k8s.io/kubelet@v0.34.0/pkg/apis/stats/v1alpha1#FsStats) field of the [ContainerStats.Rootfs](https://pkg.go.dev/k8s.io/kubelet@v0.34.0/pkg/apis/stats/v1alpha1#ContainerStats) of the Kubelet's stats API. Capacity and available are reported for the backing filesystem, which may be shared with other workloads; therefore, usage may not equal `capacity - available`. [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