Diag¶

Recipes for diagnosing CPU heat, high load, slow boots, and system errors. Available on Linux and macOS; recipes marked (Linux only) require systemd or tools not available on macOS.

For a quick command reference, jump to Examples at the end (Shift+G in the pager).

Quick Start¶

Run just sys diag check-all to print temperatures, per-core CPU usage, top processes, memory, and disk I/O in one shot. It's a good starting point when something feels slow or hot but you don't know where to look yet.

CPU¶

Temperatures — just sys diag temps (Linux only)¶

Look for the CPU line. Rough thresholds under load:

Throttling means the CPU is intentionally slowing itself down to cool off. The machine will feel sluggish even if nothing looks obviously wrong in process lists.

CPU frequency — just sys diag freq (Linux only)¶

Shows current CPU frequency, governor (e.g. performance, powersave), and available frequency range per core. Useful for confirming whether the CPU is throttled or in a power-saving mode. If a core is running well below its max frequency under load, the governor may be holding it back.

Per-core usage — just sys diag cpu-usage (Linux only)¶

mpstat prints one row per core plus an all average. The most useful columns:

• %idle — a core at 0% idle is fully saturated. Scan this column first.
• %usr — time spent running user-space code (your apps).
• %sys — time spent in the kernel on behalf of a process (syscalls, I/O).
• %iowait — time the core spent waiting for disk. High iowait means disk is the bottleneck, not CPU.
• %irq / %soft — hardware and software interrupt handling. Should be near zero; spikes suggest a driver or hardware issue.

The usr/sys split tells you what kind of work is happening:

Interactive view — just sys diag htop¶

Launches htop in tree view, sorted by CPU. The tree shows parent→child relationships — useful when a process is spawning workers and you want to see the full picture. Press F6 to change sort column, F5 to toggle tree/flat, F4 to filter by name. Press F10 or q to quit.

First-time setup: for the best experience, enable per-core temperatures and frequency display once via the UI: press F2 → Display options and toggle Show CPU frequency and Show CPU temperature. htop saves these automatically.

Top processes — just sys diag top-procs¶

A non-interactive snapshot sorted by CPU. Useful for a quick look or for piping output. Columns: PID, parent PID, command, %CPU, %MEM.

Note that %CPU is averaged over the process lifetime — a process that just spiked may show lower than you expect. If something looks wrong but nothing stands out here, use just sys diag cpu-usage to find the hot core and just sys diag core <n> to narrow down.

Processes on a specific core — just sys diag core <n>¶

Filters the process list to only what is currently scheduled on core n. Use this after just sys diag cpu-usage identifies a pegged core — it's more reliable than top-procs for pinpointing the culprit because it shows exactly what's running on that core right now.

Gotcha: if the busy time is mostly %sys, the process will still appear here but its %cpu may look deceptively low — kernel time is attributed separately. It's still your culprit.

Inspecting a process — just sys diag inspect <pid>¶

Shows the full command, elapsed run time, CPU and memory for a single process. Useful when you have a PID from core or top-procs and want to know what it is and how long it has been running. A process running for days with high CPU is a runaway; one that just started is likely doing legitimate work.

Memory¶

just sys diag mem        # default: MiB (1024-based)
just sys diag mem k      # kilobytes (Linux only — unit is ignored on macOS)

Focus on three lines:

• used memory approaching total memory — RAM is nearly exhausted; swapping will start soon if it hasn't already.
• swap used — anything above 0 means the kernel has already pushed memory out to disk. Performance will suffer.
• pages swapped in / pages swapped out — non-zero means active swapping is happening right now. This is the clearest real-time signal of a RAM problem.

Don't be alarmed by high cache/buffer usage. The kernel deliberately fills spare RAM with filesystem cache to speed up reads. It reclaims it instantly when apps need it — high cached memory is healthy, not a problem.

Simple rule: swap used > 0 and machine feels slow = RAM-constrained. Close memory-heavy apps or consider more RAM.

Disk¶

I/O statistics — just sys diag io (Linux only)¶

just sys diag io         # default: MB
just sys diag io k       # kilobytes

iostat -x prints extended stats per device. Key columns:

• r/s / w/s — reads and writes per second. High numbers aren't necessarily a problem — depends on the workload.
• rkB/s / wkB/s — throughput. Compare against your drive's rated speed to see if it's saturated.
• await — average time in milliseconds for I/O requests to complete. For SSDs, below 1ms is normal; above 10ms suggests the drive is struggling. For spinning disks, below 20ms is typical.
• %util — percentage of time the device was busy. Above 80% means the disk is a bottleneck; at 100% it's saturated and everything waiting on it stalls.

If %iowait is high in just sys diag cpu-usage and %util is high here for a specific device, that device is your bottleneck.

Filesystem usage — just sys diag df¶

Shows used/available space per mounted filesystem (tmpfs excluded). Look at the Use% column — above 90% is worth paying attention to; above 95% things start to break (logs fill, package managers fail, etc).

On Bluefin, /boot is intentionally small (~500MB) and is the most likely partition to fill up — see just sys bluefin stage-upgrade for how to handle that.

Directory usage — just sys diag du¶

just sys diag du           # current directory
just sys diag du /boot     # find what's filling /boot
just sys diag du /var/log  # find large log files

Shows the size of each item inside the target directory, sorted smallest to largest (largest at the bottom, easiest to spot). Use this after just sys diag df tells you a filesystem is nearly full — drill into the mount point to find the culprit.

Mounted filesystems — just sys diag mounts¶

A tree view of all real (non-virtual) mounted filesystems — much easier to read than raw mount output. Shows source device, filesystem type, and mount options. Useful for checking what's mounted and where, or confirming a drive mounted correctly after plugging in.

Block devices — just sys diag blocks¶

Shows all block devices (disks, partitions, swap) with their sizes, filesystem types, labels, and mount points. Good for a quick overview of physical storage layout. If a drive isn't showing up, it'll appear here without a mount point.

USB / External Drives¶

When a drive doesn't appear after plugging in, work through these in order:

Step 1 — Did USB detect it? Run just sys diag usb. If your drive isn't listed, it's a hardware or cable problem — try a different port or cable.

Step 2 — Did the kernel create a block device? Run just sys diag blocks. If the drive appeared in usb but not here, the kernel recognised the USB device but couldn't read its partition table (corrupted, unsupported filesystem, or the drive needs power cycling).

Step 3 — Did udisks pick it up? Run just sys diag udisks. If the drive appears in blocks but not here, udisks hasn't registered it for automounting — try udisksctl mount -b /dev/sdX manually (replacing sdX with the device from just sys diag blocks).

Watching events in real time — just sys diag usb-watch: run this before plugging the drive in, then plug it in and watch. You'll see add events as the kernel detects the device and creates block device nodes. If nothing appears at all when you plug in, the drive or port is dead.

Boot (Linux only)¶

Slow units — just sys diag slow-units¶

Lists every systemd service by how long it took to start, slowest first. A service taking more than 2–3 seconds is worth a second look. Common culprits: network-dependent services waiting for a connection, or storage services scanning large directories.

Note: this measures wall-clock activation time, not CPU time — a service that sleeps waiting for a dependency will look slow here even if it's doing no real work.

Critical chain — just sys diag critical-chain¶

Shows only the chain of dependencies that determined total boot time. More actionable than slow-units — fixing a slow service that's off the critical chain won't improve your boot time at all. Focus on whatever is on the critical path.

Logs (Linux only)¶

On macOS, log show requires elevated permissions and fails on managed machines. Use Console.app instead — it provides the same error log browsing with filters for level, process, and time range.

Errors — just sys diag errors¶

Shows all log entries at error severity or above from the current boot. First place to look after something unexpected happened — a crash, a device not working, a service refusing to start. Look for repeated errors (a service crash-looping) or errors that timestamp-match when you noticed the problem.

To check a previous boot (e.g. after a crash): run journalctl -p err -b -1 directly.

Kernel messages — just sys diag kernel (Linux only)¶

Hardware-level messages: disk errors (I/O error, blk_update_request), memory errors (MCE, EDAC), driver failures, USB events, thermal warnings. If just sys diag errors turns up nothing but something hardware-related is wrong, check here next.

Diagnostic Workflows¶

Hot CPU¶

1. just sys diag temps — confirm the CPU is actually hot (above ~85°C).
2. just sys diag cpu-usage — find the core at 0% idle; note the core number and the usr/sys split (high %sys means syscall-heavy work, usually file I/O).
3. just sys diag core <n> — filter to what's running on that core. The top result is almost always your culprit.
4. just sys diag inspect <pid> — confirm what the process is and how long it's been running.
5. Kill it or wait. Temps should drop within seconds.

Sluggish machine¶

1. just sys diag cpu-usage — is a core pegged (%idle near 0)? If so, follow the hot CPU workflow above.
2. Check %iowait — if high, disk is the bottleneck. Run just sys diag io and look for a device with high %util.
3. just sys diag mem — is swap in use? If so, you're out of RAM.
4. just sys diag top-procs — anything unexpected consuming CPU or memory?

External drive not showing up¶

Follow the three steps in the USB / External Drives section above.

Examples¶

just sys diag check-all        # temps, per-core CPU, top procs, memory, disk I/O in one shot
just sys diag temps            # is the CPU hot?
just sys diag freq             # CPU frequency and governor
just sys diag cpu-usage        # which core is pegged, usr or sys, iowait?
just sys diag core 13          # what's running on core 13?
just sys diag inspect 62408    # what is this process and how long has it been running?
just sys diag top-procs        # top CPU consumers across all cores
just sys diag htop             # interactive tree view
just sys diag mem              # memory and swap (MiB)
just sys diag io               # disk I/O — is a device saturated?
just sys diag df               # is any filesystem nearly full?
just sys diag du /boot         # what's filling /boot?
just sys diag mounts           # what is mounted and where?
just sys diag blocks           # physical disk and partition layout
just sys diag usb              # connected USB devices
just sys diag udisks           # automount daemon status
just sys diag usb-watch        # watch for block/USB events when plugging in
just sys diag slow-units       # what made boot slow?
just sys diag critical-chain   # what was on the critical path?
just sys diag errors           # what went wrong this boot?
just sys diag kernel           # hardware-level messages