> For the complete documentation index, see [llms.txt](https://docs.umh.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.umh.app/usage/instances/container/cpu-health/cpu-contention-while-cores-are-free.md).

# CPU Contention While Cores Are Free

The **CPU contention** status means that work in the UMH Core container had to wait for a CPU core. It can appear while the machine has free cores. Work that waits finishes late, for example a bridge reading its PLC or UMH Core applying a configuration change. The share of time spent waiting is called CPU pressure. When it rises above its **Degrades** threshold in [Thresholds](https://docs.umh.app/usage/instances/container/cpu-health.md#thresholds), the CPU health is degraded. New bridges then wait (see [When a new bridge waits for CPU](https://docs.umh.app/usage/instances/container/cpu-health.md#when-a-new-bridge-waits-for-cpu)). The CPU health recovers once pressure falls below its **Recovers** threshold.

## What to do

To lower the pressure, give the machine more cores, move other software off it, or raise the container's CPU limit if it has one. More cores help even when the machine looks idle, because more of the tasks that start together can then run at once.

## Background

Linux measures CPU pressure per container, as the share of time in which at least one task was ready to run and waited for a core. At 10%, for example, a task was waiting during about 6 of every 60 seconds.

Any program on Linux can wait for a core on a machine whose cores are free on average. A CPU usage graph averages over a second or longer, which hides a wait of a few milliseconds. A program that starts more tasks at one moment than there are cores makes the extra tasks wait. The cores can then be idle for the rest of the second. Tasks also wait when other software on the machine holds the cores. They wait as well when the container has used up its CPU limit (see **Throttling** in the [Glossary](https://docs.umh.app/usage/instances/container/cpu-health.md#glossary)).

UMH Core is one such program. Every 100 ms, it starts the checks and updates for all its bridges and data flows at the same moment. This is UMH Core's own internal work, separate from how often a bridge polls its PLC. UMH is changing UMH Core's internals to spread this work over time.

## Read the CPU pressure value yourself

Run `docker exec <container name> cat /sys/fs/cgroup/cpu.pressure` to print the value. The CPU health check uses the `avg60` value of the `some` line, as defined in the Linux kernel's [Pressure Stall Information](https://docs.kernel.org/accounting/psi.html) documentation. The kernel updates it every 2 seconds and weights recent seconds more than older ones. The 6-of-60-seconds figure above is exact only under a steady load. [Why we should get rid of average CPU utilization](https://www.theocharis.dev/blog/why-we-should-get-rid-of-average-cpu-utilization/) shows with examples how an average CPU graph hides these waits.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.umh.app/usage/instances/container/cpu-health/cpu-contention-while-cores-are-free.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
