sysray 0.5.0

Modern cross-platform system observability engine
sysray-0.5.0 is not a library.

Sysray

Modern host diagnostics in one binary.

Sysray is a system observability engine written in Rust. It is being built as a modern replacement for legacy local monitoring tools such as NMON: single binary, low overhead, cross-platform by design, and extensible from day one.

Current workspace version: 0.5.0

Positioning

Sysray is not presented as a finished enterprise platform today. What exists already is a serious technical foundation with working Linux collectors, a TUI, JSON/CSV/Prometheus exporters, a post-collection pipeline, and a cross-platform abstraction layer that is ready to receive real macOS and Windows implementations.

What Sysray aims to become:

  • A fast local observability binary for Linux, macOS, and Windows
  • A strong open core foundation for future Pro, Cloud, and enterprise offerings
  • A modern Rust-native replacement for aging system tools

Product boundary:

  • Sysray Core should include deep local diagnostics for advanced operators
  • Sysray Enterprise should add governance, fleet-level control, and shared history
  • Enterprise is not where local expert analysis gets hidden

Current Status

Current stage: early V1 foundation.

What is working now:

  • Linux collectors for CPU, memory, disk, network, process, and system metrics
  • Linux-specific cgroup v2 and PSI metrics in snapshots/exporters when available
  • Partial real macOS and Windows support for baseline host collection paths
  • Native CI validation on Linux, macOS, and Windows runners
  • Expanded Linux CI coverage across multiple Ubuntu runner versions plus a musl target check
  • Interactive TUI mode
  • One-shot snapshot export in JSON, CSV, and Prometheus text format
  • Local recording to .jsonl with built-in rotation and raw retention controls
  • Post-collection computed metrics pipeline
  • Cross-platform platform layer with Linux implementation and macOS/Windows stubs
  • Service management scaffolding for systemd, launchd, and Windows Task Scheduler
  • Shared technical reference catalog exposed in TUI, API, and CLI explain mode
  • TUI depth can continue to grow with expert local diagnostics without becoming an enterprise-only feature

What is not finished yet:

  • Real macOS collectors
  • Real Windows collectors
  • Full public launch assets: CI, tests, docs, changelog, release automation
  • Enterprise features such as RBAC, SSO, retention, multi-host orchestration, SLA-level hardening
  • Distributed scalability architecture

What We Can Honestly Claim Today

  • Written in Rust
  • Single binary application
  • Apache 2.0 licensed
  • Linux-first implementation with explicit cross-platform architecture
  • Partial host-metric parity on macOS and Windows, with deeper collectors still pending
  • Low-level system access on Linux with minimal abstraction overhead
  • Forward-compatible metric schema via serde(default)

What We Do Not Claim Yet

  • Production-ready on all platforms
  • Zero overhead
  • Enterprise-ready
  • Infinitely scalable
  • Full macOS and Windows support

Why Sysray

  • Clean internal architecture: collectors, scheduler, exporters, pipeline, platform layer
  • Rust performance and memory safety
  • Backward-compatible snapshot schema
  • Clear path from local observability tool to larger platform
  • Honest product posture: strong foundation first, marketing claims second

Commands

Use sysray --help for the live CLI and sysray <command> --help for per-command details. Built-in recording rotation, retention, and closed-segment zip compression are now in the CLI. The standalone archive command is still planned and documented in docs/help.md. The TUI now exposes a technical reference pane with / for search, ? for the index, l for the live logs pane, L to add watched paths, e for an error-focused logs view, 1 to 6 for operator presets, 7 to 0 for expert local diagnostics, g for inventory+, v for detail density, and i to switch fr/en. The Linux panel toggle now lives on k so l stays dedicated to logs. The index follows the active language and specialist view context. In practice, io is the broad storage preset, disk+ is the contention/performance drill-down, and inventory+ is the local topology / stack / refs view. The logs pane now follows active files incrementally with offset tracking and rotation/truncation detection.

Screens

Overview TUI:

Sysray TUI overview

Expert network view:

Sysray expert network diagnostics

Expert pressure view:

Sysray expert pressure diagnostics

Expert JVM view:

Sysray expert JVM diagnostics

Expert disk view:

Sysray expert disk diagnostics

Disk inventory view:

Sysray expert disk inventory

These captures are generated from real terminal frames with:

bash scripts/capture-tui-screens.sh docs/screenshots

# Interactive TUI
sysray

# One-shot snapshot
sysray snapshot --format json

# Continuous recording
sysray record --interval 5s --output ./captures --rotate hourly --keep-files 48 --compress zip

# HTTP server
sysray server --port 9090

# Top processes
sysray top --sort cpu --limit 20

# Watch one process
sysray watch --pid 1234

# Replay a recorded session
sysray replay ./captures/sysray_20260303_130000.jsonl

# Explain a technical term
sysray explain latency
sysray explain swap --lang en --audience beginner

# Service integration
sysray service install
sysray service status
sysray service uninstall

Linux Install And Update

On Linux, install the release binary to a stable path instead of running from target/debug/ or target/release/.

Current Linux packaging assumptions:

  • build and runtime target the generic Linux kernel surface, not a named distribution
  • service installation is currently systemd-oriented
  • non-systemd distributions can still run the binary, but the bundled service installer is not a universal Linux service manager

Recommended user-level install:

./scripts/install-linux-user.sh

This script:

  • builds the release bundle if dist/ is missing
  • installs the release binary to ~/.local/bin/sysray
  • reinstalls the user service so it points to that stable binary path

For a fresh rebuild from the current workspace before install:

./scripts/install-linux-user.sh --force-build

For a binary-only update without touching the service:

./scripts/install-linux-user.sh --no-service

Manual update flow:

./scripts/build-complete.sh
install -m 755 dist/sysray-<version>-<target>/standalone/sysray ~/.local/bin/sysray
~/.local/bin/sysray service uninstall
~/.local/bin/sysray service install
systemctl --user status sysray.service

Configuration

Example configuration is available in config/sysray.toml.example.

Sysray uses:

  • Config file: sysray.toml
  • Env var: SYSRAY_CONFIG
  • Binary name: sysray

Recording defaults can now also be centralized in the config file:

  • record.interval_secs
  • record.output
  • record.rotate
  • record.max_file_size_mb
  • record.keep_files
  • record.compress

TUI defaults can also be centralized:

  • tui.theme
  • tui.locale

Architecture

src/
├── main.rs
├── cli.rs
├── config.rs
├── service.rs
├── engine/
├── collectors/
├── exporters/
├── pipeline/
├── platform/
├── tui/
└── api/

Key design points:

  • collectors/: metric gathering and snapshot population
  • platform/: OS-specific boundary
  • pipeline/: derived metrics and alerts
  • engine/: scheduling and runtime orchestration
  • exporters/: output formats
  • service.rs: OS service integration

Detailed planning documents:

Cross-Platform Strategy

Sysray is cross-platform by architecture today, not yet by implementation completeness.

That distinction matters:

  • Linux: real collector implementation
  • macOS: baseline CPU, memory, disk, network, process, and system collection paths implemented, broader parity pending
  • Windows: baseline CPU, memory, disk, network, process, and system collection paths implemented, broader parity pending

Validation is tracked separately from implementation:

  • Linux: validated locally and in CI
  • macOS: baseline implementation present and validated in native CI, with broader parity still pending
  • Windows: baseline implementation present and validated in native CI, with broader parity still pending

Linux support should also be read carefully:

  • the code targets Linux generally, not an explicit matrix of every distribution
  • collector compatibility primarily depends on standard kernel interfaces such as /proc
  • service management compatibility depends on the init system, and only systemd is bundled today

The goal is that adding or improving an OS implementation happens primarily inside src/platform/, not by scattering conditional compilation across collectors.

Validation policy is documented in docs/cross-platform-validation.md.

Public Roadmap

V1

  • Stabilize Linux collectors
  • Add tests and CI
  • Finish public repository assets
  • Improve TUI polish and exporter coverage
  • Validate service installation flows

V2

  • Real macOS support
  • Real Windows support
  • JVM and container depth
  • Replay and alerting improvements

V3

  • Multi-host architecture
  • Web and API ecosystem
  • Advanced enterprise features

For a stricter breakdown of what belongs to V1, V2, V3, and enterprise scope, see docs/product-scope.md.

Community And Enterprise

Sysray Core is intended to stay community-accessible and open source. That community/core layer should keep getting the main local observability primitives: collectors, TUI, exporters, replay, Linux depth, and cross-platform baseline support.

The enterprise track is a separate concern:

  • governance and access control
  • supportability and release discipline
  • compatibility guarantees
  • hardened deployment and auditability

Enterprise should add operational guarantees around the core, not replace the community roadmap or hide core host observability behind a paywall.

Build

cargo build

Benchmarking

Use the Linux benchmark harness to measure local overhead before making performance claims:

./scripts/benchmark-overhead-linux.sh --duration 30 --interval 5 --snapshot-count 25

Results are written under .benchmarks/<UTC_RUN_ID>/ with both summary.md and summary.csv.

On the March 3, 2026 Rocky Linux baseline run (30s, 5s, 25 snapshots), sysray record measured about 0.35% average CPU and ~13 MB RSS, while repeated one-shot JSON snapshots measured about 0.83% average CPU with a similar peak RSS. See docs/benchmarking.md.

cargo build only rebuilds the workspace binary in target/debug/. It does not update the user service binary installed in ~/.local/bin/sysray.

Dev Workstation Update Flow

For this local Linux developer setup, the user service runs the installed binary path, not the build output from target/debug/.

Current service runner:

  • ~/.config/systemd/user/sysray.service -> ~/.local/share/sysray/sysray-service.sh
  • ~/.local/share/sysray/sysray-service.sh -> ~/.local/bin/sysray

Recommended flow after code changes:

./scripts/redeploy-dev-user-service.sh

This script runs:

  • cargo fmt --all
  • cargo clippy --all-targets -- -D warnings
  • cargo test
  • cargo build
  • ./scripts/install-linux-user.sh --force-build
  • systemctl --user restart sysray.service
  • systemctl --user status sysray.service --no-pager
  • journalctl --user -u sysray.service -n 50 --no-pager

If you only run cargo build, you have rebuilt the dev binary in target/debug/, but the service still uses the installed binary in ~/.local/bin/sysray until you reinstall it.

If you want the manual flow instead of the helper script:

cargo fmt --all
cargo clippy --all-targets -- -D warnings
cargo test
cargo build
./scripts/install-linux-user.sh --force-build
systemctl --user restart sysray.service
systemctl --user status sysray.service --no-pager
journalctl --user -u sysray.service -n 50 --no-pager

Complete Build

Run the full local release flow in one command:

./scripts/build-complete.sh

This command runs:

  • cargo fmt --all -- --check
  • cargo clippy --all-targets -- -D warnings
  • cargo test
  • cargo build --release

It then creates:

  • dist/sysray-<version>-<target>/standalone/
  • dist/sysray-<version>-<target>/install-prereqs/
  • dist/sysray-<version>-<target>.tar.gz
  • dist/sysray-<version>-<target>.zip on Windows targets
  • dist/sysray-<version>-<target>.SHA256SUMS
  • dist/sysray-<version>-<target>.SHA256SUMS.asc when gpg is available and SYSRAY_GPG_KEY_ID is set

CI runs this same script on Linux, macOS, and Windows and uploads the generated dist/ artifacts automatically.

Release publication on GitHub is triggered by pushing a v* tag and requires the signing secrets documented in docs/release-process.md.

License

Apache License 2.0.

Sysray Core is intended to remain open source.

Author

Kevin Vanden-Brande