top and htop: Live CPU and Memory on a Runner
top shows a live, sorted view of CPU and memory per process, plus the load average and CPU-state breakdown for the whole machine.
top is the at-a-glance health check for a runner: which process is hot, how much memory is free, and whether the box is CPU-bound or stuck waiting on I/O.
What it does
top refreshes a process table sorted by CPU by default. The header shows load average, task counts, and a CPU line where us is user, sy system, id idle, and wa is I/O wait. The Mem and Swap lines show free vs used. Batch mode (-b -n1) prints one non-interactive snapshot, the only form usable in CI logs.
Common usage
top -b -n1 | head -20 # one snapshot, scriptable
top -b -n1 -o %MEM | head -20 # sorted by memory
# inside interactive top: press M (mem), P (cpu), 1 (per-core), q (quit)
htop # nicer interactive alternativeOptions
| Flag / key | What it does |
|---|---|
| -b | Batch mode: plain text, no curses (for CI) |
| -n <N> | Number of refresh iterations then exit |
| -o <field> | Sort by a field, e.g. %MEM or %CPU |
| -p <pid> | Monitor only specific PIDs |
| M / P (interactive) | Sort by memory / by CPU |
| 1 (interactive) | Toggle per-core CPU display |
In CI
Never run bare top in a job; it is interactive and the step hangs. Use top -b -n1 for a snapshot. A high wa (I/O wait) with low us means the build is disk-bound, not CPU-bound, so more cores will not help. A load average well above the core count (see nproc) means the runner is oversubscribed.
Common errors in CI
Plain top in a non-interactive shell prints "top: failed tty get" or simply produces no parseable output and waits forever; always pass -b -n1. If memory looks alarmingly low, remember Linux uses free RAM for cache: the "available" figure from free is the real headroom, not "free".