Scope
Static facts read once and cached (OS name and version, CPU model, core counts, CPU features, caches, topology, virtualization, form factor); live readings read fresh on every call with no allocation for single values (memory, swap, uptime, load, disk space, this process's memory and CPU time); caller-owned samplers for values that need two readings (CPU usage, network rates); the boot kit (build info, instance info, process guard); and an opt-in device id derived with a keyed hash, so raw hardware identifiers never leave the library. It does not inspect other processes, change system settings, or run in the background.
Quick start
Cargo's rename makes the crate sys in your code:
[]
= { = "sys-lib", = "0.4" }
Tier 1 is one plain call per fact. Static facts are read once and cached, so every later call costs about a nanosecond:
println!; // "Ubuntu 24.04.1 LTS", "macOS 15.1 Sequoia", "Windows 11 Pro"
println!; // "Ubuntu"; "Windows" and "macOS" elsewhere
println!; // "AMD Ryzen 9 7950X"
println!;
println!; // the container's quota, not the host's count
println!; // "build-07"
if is_64bit && is_like
// Live readings: read now, container-aware.
println!; // "41.2 GiB of 125.6 GiB" (the cgroup's limit inside a container)
println!; // "12.4%" (blocks for 100 ms)
let t = traffic?; // blocks 1 s
println!; // "down 12.5 MiB/s up 1.2 MiB/s"
println!;
A monitor keeps samplers instead of blocking: each is owned by the caller, never sleeps, and allocates nothing per sample:
let mut cpu = new?;
let mut net = new?;
loop
The boot kit, for a long-running service's first milliseconds:
// build.rs
Tier 2 adds detail behind the same modules (sys::os::info(), sys::os::os_release(),
sys::process::Guard::builder(..)); errors say what failed and what to do,
and a fact the OS does not expose is Error::Unsupported, never a guess.
Planned through 0.6
let v = detect; // 0.5: VM, container, WSL, cloud
let id = id?; // 0.5: an application-scoped device id
let r = report; // 0.6: is this host fit to serve?
The complete planned API, with the version each item arrives in, is in docs/API.md; where every value comes from on each operating system is in docs/SOURCES.md. See dev/PLAN.md for the full scope, what is deliberately left to other crates, and the decision log.
Contributing
See dev/DIRECTIVES.md for engineering standards and the definition of done. Before a PR: cargo fmt --all, cargo clippy --all-targets --all-features -- -D warnings, and cargo test --all-features must be clean.