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.6" },
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.5.0, detection and identity: the boot kit (os, cpu, host,
process, build, and instance info), the live readings (mem,
disk, net), virt, power, summary(), and device identity
behind the device-id feature. The environment reports, FreeBSD, and 32-bit
Linux arrive in 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;instancepub 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.
- device
device-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.
- instance
instance - 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.
- probe
Linux - 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 calledbuild::emitstill compiles, with the commit, time, target, and rustcunknown(E-60).
Structs§
- Bytes
- A byte count: an exact
u64inside, with aDisplaythat 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.
- Pressure
Level - How serious a
Pressurereading is. Ordered:Normal < Warning < Critical. - Units
- Which unit system
Bytes::displayuses.
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
Nonein its field.
Type Aliases§
- Result
- The result type used throughout sys-lib.