# Semantic conventions for container metrics **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.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] |  | | **[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 [opt-in][MetricOptIn]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | | -------- | --------------- | ----------- | -------------- | --------- | ------ | | `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/registry/attributes/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 | Entity Associations | | -------- | --------------- | ----------- | -------------- | --------- | ------ | | `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/registry/attributes/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 | Entity Associations | | -------- | --------------- | ----------- | -------------- | --------- | ------ | | `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 | Entity Associations | | -------- | --------------- | ----------- | -------------- | --------- | ------ | | `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/registry/attributes/disk.md) | string | The disk IO operation direction. | `read` | `Recommended` |  | | [`system.device`](/docs/registry/attributes/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 | Entity Associations | | -------- | --------------- | ----------- | -------------- | --------- | ------ | | `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/registry/attributes/network.md) | string | The network interface name. | `lo`; `eth0` | `Recommended` |  | | [`network.io.direction`](/docs/registry/attributes/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: `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] |  | [`container`](/docs/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] |  | [`container`](/docs/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] |  | [`container`](/docs/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]: https://opentelemetry.io/docs/specs/otel/document-status [MetricOptIn]: /docs/general/metric-requirement-level.md#opt-in [MetricRecommended]: /docs/general/metric-requirement-level.md#recommended