Semantic conventions for container metrics

Status: Development

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

This metric is recommended.

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.

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	Stability
cpu.mode	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	IO Wait
kernel	Kernel
nice	Nice
steal	Steal
system	System
user	User

Metric: container.cpu.usage

This metric is opt-in.

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	Stability
cpu.mode	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	IO Wait
kernel	Kernel
nice	Nice
steal	Steal
system	System
user	User

Metric: container.memory.usage

This metric is opt-in.

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.

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	Stability
disk.io.direction	string	The disk IO operation direction.	read	Recommended
system.device	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.

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	Stability
network.interface.name	string	The network interface name.	lo; eth0	Recommended
network.io.direction	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.

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
container.filesystem.available	UpDownCounter	By	Container filesystem available bytes. [1]		container

[1]: In K8s, this metric is derived from the FsStats.AvailableBytes field of the ContainerStats.Rootfs of the Kubelet’s stats API.

Metric: container.filesystem.capacity

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
container.filesystem.capacity	UpDownCounter	By	Container filesystem capacity. [1]		container

[1]: In K8s, this metric is derived from the FsStats.CapacityBytes field of the ContainerStats.Rootfs of the Kubelet’s stats API.

Metric: container.filesystem.usage

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
container.filesystem.usage	UpDownCounter	By	Container filesystem usage. [1]		container

[1]: This may not equal capacity - available.

In K8s, this metric is derived from the FsStats.UsedBytes field of the ContainerStats.Rootfs of the Kubelet’s stats API.