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 by default (the device-id feature brings crypt-io’s BLAKE3 stack).

§Tier 1

Add it with Cargo’s rename, sys = { package = "sys-lib", version = "0.7" }, 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.7.0, optimisation: every reading measured against the crates people use for it, with the numbers in docs/PERFORMANCE.md. Feature complete since 0.6: the boot kit (os, cpu, host, process, build, and instance info), the live readings (mem, disk, net), virt, power, summary(), the environment reports, device identity behind the device-id feature, on Linux (64- and 32-bit), macOS, Windows, and FreeBSD. The complete API 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§

bench
The benchmark environment: what a result needs printed next to it so it can be trusted and repeated.
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.
devicedevice-id
Device identity: an id for “this device” that an application can store and recognise later.
disk
Disks and filesystems: free space, the mounted filesystems, and how hard the disks are working.
gpu
Graphics adapters.
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.
power
The system battery and mains power.
probeLinux
Explicit roots for monitoring agents (Linux).
process
This process: its id, the user it runs as, whether it is elevated, and the process guard every long-running service starts with.
readiness
The server readiness report: the operating-system settings that decide whether a server performs and stays up under load, each with the reason and the fix, the way enterprise databases warn at start-up.
security
The machine’s security settings, read-only.
sensors
Temperatures.
virt
Virtualization and containers: what this program runs inside.

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.
Summary
See summary. It deliberately carries no host name, user name, MAC address, or device id, because it is meant for output that leaves the machine (threat T13).

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.

Functions§

summary
The facts for a log line or a support bundle. Never fails: a reading that fails becomes None in its field.

Type Aliases§

Result
The result type used throughout sys-lib.