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

The data plane

Every display surface in ltop is backed by one serialized snapshot — schema v1, versioned with the binary so scripts and agents can rely on it. The same structs serialize into all of these:

SurfaceCommandShape
one-shot snapshotltop --jsonsingle JSON object (~8k tokens unfiltered)
field referenceltop --schemaversioned machine-readable field list
monitoring logL / --logJSONL, one snapshot per log_interval_ms (default 60 s)
headless captureltop watchJSONL, one snapshot per --interval (default 5 s)
window summaryltop reporthuman table, or one ~2 KB JSON object with --json
ltop --json      # structured snapshot (takes ~1.2 s: two sampling rounds
                 # so rate fields are populated)
ltop --schema    # the authoritative field list — versioned with the binary,
                 # never drifts from it

The snapshot covers five domains: meta (version, os, arch, udp_helper flag), net (per-interface rates and cumulative counters), procs (per-process network + disk accounting with UDP breakdown), conns (per-connection sockets), disk (capacity/throughput), and lan (neighbours). Semantics worth knowing are marked right in the output — e.g. macOS MAC sanitization (real values once ltop lan-setup is installed).

Monitoring log (TUI)

L in the TUI, or start with --log, records snapshots to ~/.local/state/ltop/ltop-log-<ts>.jsonl:

  • log_interval_ms (default 60 000) sets the cadence; log_tracked_only = true records only tracked processes.
  • log_retention_days (default 7) purges old files at startup and when toggled.

Headless watch

ltop watch --duration 10m --proc chrome   # full syntax in `ltop watch --help`
  • Stops on --duration (10s/5m/2h), a --stop sentinel file (consumed on sight), or SIGINT — which is graceful: the last snapshot lands in the file.
  • Output defaults to ~/.local/state/ltop/ltop-session-<ts>.jsonl, separate from the TUI monitoring log and exempt from its retention purge; its own --retention (default 7 days, 0 = keep forever) prunes at start.
  • Line-by-line appends are crash-safe; no root required.
  • --proc <name> focus mode records only matching processes and their connections — tracked by name, so a restart that changes the pid keeps the timeline continuous.
  • Write volume scales with the interval (1 s ≈ 8 KB/line ≈ 28 MB/h; the 5 s default is ~5–6 MB/h). --retention is the cleanup story.

Report

ltop report <file.jsonl> [--json]

Reads a watch capture or a TUI monitoring log (same schema) and produces the window summary: per-process window sums (window differencing across pid restarts), peak rates, active time, last alive/exited state; per-connection sums/peaks/lifetimes keyed by inode (vanished connections keep their last known totals); NIC-scope global totals and the peak interval.

Filters: --top N (default 5, by traffic), --proc (substring, or glob when it contains *), --fields net,udp,disk,conns, and --json for the machine-readable form. The AI workflow built on this lives in AI agents.

Legacy and debugging

  • ltop --dump — one human-readable sampling round to stdout (debugging; prefer --json for parsing, the dump truncates and misaligns values).
  • ltop --replay [--csv OUT] [--top N] — rebuilds session deltas from legacy session-* logs (v1, procs-only) and exports CSV. Current-format files belong to report; old ones are rejected with a pointer here.

Configuration

~/.config/ltop/config.conf is plain key = value, written by the in-app settings panel (m → settings) and safe to hand-edit (applies on restart):

KeyDefaultMeaning
langenUI/messages language; zh switches all human output to Chinese (JSON keys stay English)
layoutclassicstart layout (classic/wide/tall)
tick_ms1000refresh interval
graph_net / graph_diskhybrid / centereddefault chart style
boxesall onvisible boxes
log_interval_ms60000monitoring log cadence
log_retention_days7monitoring log purge age
log_tracked_onlyfalselog only tracked processes
sweep / sweep_interval_strue / 60LAN UDP-knock sweep on/off and cadence
tombstone_ttl_ms5000how long closed connections linger in CONNS
themeomarchytheme name (see Themes)
theme_live_followfalsere-color a running ltop on Omarchy theme change (same as --follow-theme)
proc_expand_defaultfalseCONNS process groups start expanded
proc_exit_retention_min30evict exited-process ledgers after N minutes (0 = forever)
conn_filter / conn_sort / proc_sort / lan_sortall / proc / net-sum / ipdefault list modes
allow_global_killfalseallow killing other users’ processes
net_graph_coupledfalsecoupled NET chart scaling: when one direction dwarfs the other, the small side renders at its true fraction of the chart height instead of auto-scaling to full height
net_graph_scale_ratio5trigger threshold for the above, in×(2–20); ratios below it keep normal auto-scaling