Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

FAQ

The rx and tx charts have the same shape

Not a bug — two effects stacking. Each chart scales to its own window peak (btop-style, so small movements stay readable), and during a download your uplink is almost entirely TCP ACKs, whose rate tracks the downlink’s packet rate one-to-one. The tx/rx ratio you’ll see is ~1/30 — exactly the expected ACK share (one ACK per ~2 segments, ~66 bytes per ~2900 bytes of data); the graph then blows that tiny waveform up to full height, so the two curves look like siblings. When the two directions differ this much, read the header numbers, switch the graph mode to Block (m → graphs), or turn on coupled scaling so the small side renders at its true fraction of the chart height: m → graphs → c (persist with net_graph_coupled = true; the trigger ratio is net_graph_scale_ratio, default 5×).

PROCS totals are lower than the NET box

By design, on every platform. The NET box counts interface bytes (driver level: every packet, including headers, retransmits and background chatter). PROCS counts payload bytes attributed to processes (eBPF at the syscall on Linux; live-socket accounting on macOS), and only for your own processes on some platforms. The gap is the sum of everything that is interface traffic but not your processes’ payload. See eBPF accounting → What the numbers mean.

CONNS totals include traffic from before ltop started

Also by design, and TCP-only: a TCP connection’s Σ comes from the kernel’s per-socket counters, which cover the connection’s whole life — including time before ltop launched. UDP Σ is session-accumulated by ltop from the moment the helper is live. That difference (plus headers) is part of why CONNS and PROCS totals don’t match each other either; traffic through a proxy is attributed to the proxy process.

Per-process accounting zeroed after an upgrade

A stale ltop-bpf keeps writing its snapshot to the old path while the new TUI diffs against a different file — the symptom is per-process numbers silently reading zero. Fix: always re-deploy the helper with the TUI:

sudo cp ltop-bpf /usr/local/bin/          # from the same release as the TUI
sudo systemctl restart ltop-bpf

UDP columns are missing / partial

On Linux this means the eBPF helper is not running — check meta.udp_helper in ltop --json and deploy it (no root needed for the TUI itself; TCP columns keep working from socket sampling without the helper). On macOS UDP per-process numbers come from sampled live sockets and transfers that complete within one tick are not counted — a documented platform difference, not a bug.

conns[].process is null for some connections

Those sockets belong to other users (Linux): attribution scans your own uid’s sockets. “null” means “not attributable to you”, not “unrelated to any process”.

CONNS has a group named “n/a” (uid:4294967295 in older versions)

macOS counterpart of the above: the unprivileged TUI can only attribute sockets of your own user (libproc, same semantics as reading your own /proc/<pid>/fd on Linux). Connections belonging to other users, system daemons or the kernel are visible as traffic but not attributable to a process, so they group under n/a — 0.2.12 and later; older builds printed the raw uid:4294967295 sentinel, which is the same bucket. This is a permission boundary, not missing data. To see the owners resolved, run sudo ltop once (root can enumerate every process and the group empties out); only do so if you are comfortable running a monitor as root.

One-shot --json takes ~1.2 s

Two sampling rounds run back-to-back so every rate field is populated from a real delta. For scripting, that latency buys you rates instead of counters-only; --dump skips it but truncates values — parse --json.

watch filled my disk

Write volume scales with --interval: 1 s ≈ 8 KB/line ≈ 28 MB/h; the 5 s default is ~5–6 MB/h. Captures default to --retention 7 days (purged at the next watch start; 0 keeps forever). Long-term recording is the monitoring log’s job (L / --log), which defaults to 60 s granularity and 7-day retention.

The loli command is gone

Retired in 0.2.4 — it was a leftover from the original localist top naming, and tarballs/brew/AUR no longer ship it. Make your own alias if you liked it (help follows the invoked name):

ln -s "$(command -v ltop)" ~/.local/bin/loli

AUR package?

ltop-bin is built and waiting for the AUR to reopen account registration. Until then: Homebrew, crates.io or GitHub Releases.

Missing braille glyphs (boxes render as ? or blank)

Your terminal font lacks Unicode braille. Use a proper terminal emulator fonts-and-all, or render over SSH — bare framebuffer consoles may miss the glyphs. On macOS this affects the built-in Terminal’s framebuffer rendering in particular.

Old kernels / cloud images

glibc 2.35+ and a kernel with kprobes are the runtime floor for the eBPF helper; the TUI itself runs on anything the binary links against. Ubuntu’s -kvm cloud kernel trims kprobes — use the generic kernel. Ubuntu 22.04’s 5.15 works without BTF (CO-RE resolves at load time).

Does ltop phone home?

No telemetry, ever. The only outbound activity is the LAN sweep: small UDP packets to your own subnet (default every 60 s, sweep = false to disable) that make the kernel resolve neighbours via ARP — no port probing, no raw sockets, no traffic beyond your connected prefixes.

How do I get the report as JSON for my agent/script?

ltop report <file.jsonl> --json

… and read AI agents — including why polling --json in a loop wastes ~40k tokens per 10 minutes versus ~1k for a report.