Skip to main content

Crate sys_lib

Crate sys_lib 

Source
Expand description

§sys_lib

System facts for Rust services, container-aware by default, plus the boot kit every long-running service needs in its first milliseconds: build info, instance info, and a process guard.

Every reading is a file read or a system call. sys-lib never starts a thread or a timer, never runs another program, and has no third-party runtime dependencies.

§Tier 1

Add it with Cargo’s rename, sys = { package = "sys-lib", version = "0.4" }, and every file writes sys::; without the rename, use sys_lib as sys; does the same (the examples use that form so they compile either way). One plain call per fact; static facts are read once and cached:

use sys_lib as sys;

println!("{}", sys::os::name());         // "Ubuntu 24.04.1 LTS", "macOS 15.1 Sequoia", "Windows 11 Pro"
println!("{}", sys::os::distro());       // "Ubuntu"; "Windows", "macOS" elsewhere
println!("{}", sys::cpu::name());        // "AMD Ryzen 9 7950X"
println!("{} cores, {} threads", sys::cpu::physical(), sys::cpu::logical());
let workers = sys::cpu::available();     // what this process may use: affinity, cpuset, quota
println!("{} of {} used", sys::mem::used()?, sys::mem::total()?);  // the container's limit inside one
println!("{} free here", sys::disk::space(".")?.available);

The boot kit:

use sys_lib as sys;

let _guard = sys::process::guard("site")?;   // single-instance lock, umask, open-file limit
let build = sys::build_info!();              // with `sys::build::emit()` in build.rs
let instance = sys::Instance::start();
println!("{build}\n{instance}");

§Status

0.4.0, live readings: the boot kit (os, cpu, host, process, build, and instance info), mem, disk, net, and CPU usage, load, pressure, and features. Virtualization, power, device identity, and the environment reports arrive through 0.6; the complete approved API, each item with the version it arrives in, is docs/API.md in the repository.

Re-exports§

pub use build::BuildInfo;
pub use build::PublicBuild;
pub use instance::Instance;instance
pub use instance::InstanceId;instance

Modules§

build
Build info: facts fixed when the application was compiled, answering “exactly which build is running?” in logs, crash reports, and health checks.
cpu
The processor: architecture and bitness, name and vendor, the counts (cores, hardware threads, sockets, and what this process may use), the frequency, usage, load, pressure, and instruction-set features.
disk
Disks and filesystems: free space, the mounted filesystems, and how hard the disks are working.
host
The machine and its environment.
instanceinstance
Instance info: facts fixed when this process started, answering “which running copy is this?” when several run at once. Put the instance id in every log line, audit record, and metric so events from two processes are never mixed up.
mem
Memory: how much there is, how much is in use, and how much this process may use, container-aware by default.
net
Network interfaces, download and upload, and connection counts.
os
The operating system: kind, name, version, kernel, and distribution.
process
This process: its id, the user it runs as, whether it is elevated, and the process guard every long-running service starts with.

Macros§

build_info
The application’s build info, as a &'static BuildInfo. Expands in the calling crate, so the name and version are the application’s. An application that never called build::emit still compiles, with the commit, time, target, and rustc unknown (E-60).

Structs§

Bytes
A byte count: an exact u64 inside, with a Display that picks the unit.
Mhz
A clock frequency in megahertz.
Percent
A share between 0 and 100 percent, never NaN.
Pressure
How much work is stalled waiting for a resource (CPU, memory, or I/O).
Rate
A transfer rate in bytes per second, for network download and upload and disk read and write.
Stall
The share of time tasks were stalled, averaged over the last 10, 60, and 300 seconds.

Enums§

Error
Everything that can go wrong in sys-lib.
PressureLevel
How serious a Pressure reading is. Ordered: Normal < Warning < Critical.
Units
Which unit system Bytes::display uses.

Constants§

VERSION
Crate version string, populated by Cargo at build time.

Type Aliases§

Result
The result type used throughout sys-lib.