In this article, we will clarify how resource usage graph calculation works in CircleCI, focusing on the distinction between single-threaded and multi-threaded scenarios. This explanation is based on a discussion with our development team and should provide a clear understanding of how CPU load is calculated and represented in our graphs.

The resource usage graph in CircleCI shows the aggregate usage of all threads/cores. For example, given a 4CPU VM, a 25% load could mean both 100% load of a single core as well as 25% load across the four cores. This is calculated by a stats collector function in our code.

The return value from this function should be a value between 0 and the count of CPUs. However, it's important to note that this does not show whether we mean "one core pinned to the max" or "two cores working at 50%" each. We prioritize visualizing parallel runs in this graph rather than individual thread workloads.

When it comes to Docker workloads, discerning the CPU load becomes more complex. As a user, you don't really get a specific number of CPUs. Instead, you get an amount of time scheduled in the CPUs equivalent to the number of allocated CPUs. Your compute might occur across multiple different CPUs.

Therefore, any graph showing individual CPU loads would be only representative. For instance, if the graph shows CPU A was at 10% load and CPU B was at 99% load, this would not accurately represent the actual distribution of compute across the CPUs.

It is currently not possible to discern between the two cases (i.e., one core at 100% load vs. four cores at 25% load each) without running something like htop when tunneled into the container. The host CPU and container CPU load add an extra layer of complexity to this.