Instana

 View Only

 What does cpu.total_usage report in containerd?

Jump to  Best Answer
  • REST API
Akamas Akamas's profile image
Akamas Akamas posted 05/22/26 08:24 AM
For the metric cpu.total_usage on the containerd plugin (returned by POST /api/infrastructure-monitoring/metrics), what is the precise unit and range?
 
Specifically: is 1.0 equivalent to one fully-utilized CPU core (i.e. the value can exceed 1.0 on multi-core containers, capped by the container's CPU limit or host core count), or is it a normalized 0–1 fraction? Or something else altogether? The metric metadata declares formatter: PERCENTAGE but we observe values up to ~2.0 on a container with cpu_limit = 2000m, which suggests the unit is "cores", not “fraction”.
Does anyone know anything about this? I have been search in the docs without success
Israel Ochoa's profile image
Israel Ochoa posted 05/28/26 05:15 AM  Best Answer

Hi Akamas,

Based on this part of the documentation:

https://www.ibm.com/docs/en/instana-observability?topic=technologies-monitoring-cri-o#ariaid-title11

The underlying source value cpuTotalUsage represents a percentage (ratio) calculation derived from nanoseconds.

The Linux kernel (via cgroups) tracks container processing in raw time counters called cpuTotalUsageNanoseconds. To make this actionable, the Instana agent evaluates these counters over a specific time window.

cpuTotalUsage = (cpuTotalUsageNanoseconds / systemTime)

  • cpuTotalUsageNanoseconds: The total amount of CPU time (in nanoseconds) used by the container's processes during that monitoring time window.
  • systemTime: The total wall-clock system time available during that exact same window.

It's a unitless ratio (decimal value) and Instana multiplies this ratio by 100 and formats it as a Percentage.

Now, the real question, How to interpret this number?
The value represents how many complete CPU cores the container fully occupied during that interval.
  • If the UI reads 50% (0.5), the container used exactly half of one CPU core's processing capacity over that time window.
  • If the UI reads 100% (1.0), the container completely saturated exactly one CPU core.
  • If the UI reads 250% (2.5), the workload was distributed, consuming the equivalent power of (2.5) fully taxed CPU cores.

And that's it, this is my understanding for that metrics and I hope it helps you.

Related Content