How facebookincubator/below works
Project type & purpose
• This is a Rust-based, CLI-driven system-monitoring tool ("below") that supports live viewing, recording, replaying, dumping, and snapshotting of Linux system data (cgroups, fs stats, PSI, etc.).
• It’s organized as a Cargo workspace with one top-level binary crate (“below”) plus ~12 library crates (e.g., btrfs, cgroupfs, model, store, view, dump, render, etc.) supplying plugins, data models, storage, UI, and exporters.
High-level layers
a. CLI & orchestration (binary crate under src/main.rs)
b. Data collection plugins (crates: btrfs, cgroupfs, procfs, ethtool, resctrlfs, tc, gpu_stats, plus BPF code in src/bpf)
c. Core abstractions & model (crates: common, model, config)
d. Storage & export (crates: store, dump)
e. Rendering & interactive UI (crates: render, view)
Inter-component flows
• “below live”:
– CLI invokes plugin collectors → raw samples → model transforms → view (TUI) or render (default configs)
• “below record”:
– collectors → model → store persists (CBOR or remote via store::open_source::remote_store)
– service unit (etc/below.service) & systemd/OpenRC integration
• “below replay”:
– store reads historical data → model → view/render
• “below dump”:
– collectors → model → dump formats to JSON/CSV/OpenMetrics → external tools (Prometheus scrape → Grafana dashboards in contrib/grafana)
• Configuration:
– config crate loads CLI flags / config file (docs/belowrc.md) → influences collector parameters, view filters, dump formats.
Architectural patterns & principles
• Modular crates-per-responsibility: each subsystem (fs, cgroup, network, GPU, BPF) lives in its own library crate.
• Plugin-style collector interfaces: dynamic dispatch over common traits in common and model.
• Clear separation of concerns (MVC-ish):
– Model = model crate
– View = view + render crates
– Controller = CLI command dispatcher in src/main.rs
• Single event loop per command (live/replay) feeding data through a channel to the UI or store.
• Use of derive macros (below_derive) to reduce boilerplate in plugin implementations.
Elements
• Clear labels: crate names & responsibilities (e.g., “model: unifies sample representation”).
– Blue = live/replay pipeline
– Green = record pipeline
– Orange = dump/export pipeline
– Solid for in-process crates