From 8f4244ae572b0697ca7602a9542c285e511c6238 Mon Sep 17 00:00:00 2001 From: rustfuture <121799572+rustfuture@users.noreply.github.com> Date: Sun, 27 Sep 2026 22:04:08 +0300 Subject: [PATCH] =?UTF-8?q?docs:=20showcase=20pass=20=E2=80=94=20clearer?= =?UTF-8?q?=20README,=20evidenced=20claims,=20limitations?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Rewrites the README first screen so the project, its status and a working quick start are clear at a glance; every technical claim now links to the code or document that backs it, and hype wording is removed. Adds a Scope and limitations section and tightens .gitignore. No code changes. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01LyzVuFLzBEdzqiwEAyXymy --- .gitignore | 9 +++++++++ README.md | 38 +++++++++++++++++++------------------- docs/architecture.md | 2 +- 3 files changed, 29 insertions(+), 20 deletions(-) diff --git a/.gitignore b/.gitignore index 9232dad..bf2d14e 100644 --- a/.gitignore +++ b/.gitignore @@ -28,5 +28,14 @@ Thumbs.db test_config.json grainx_stats.* +# Python artifacts and virtualenvs +__pycache__/ +*.pyc +*.pyo +.venv/ +venv/ +.ipynb_checkpoints/ + # Temporary files tmp_* + diff --git a/README.md b/README.md index 52572c5..b1d5e67 100644 --- a/README.md +++ b/README.md @@ -1,25 +1,21 @@ # grainx +A terminal system monitor and local HTTP metrics service in Rust for developers and operators monitoring system resources and process activity. + [![CI](https://github.com/rustfuture/grainx/actions/workflows/ci.yml/badge.svg)](https://github.com/rustfuture/grainx/actions/workflows/ci.yml) -[![Rust](https://img.shields.io/badge/rust-1.88%2B-orange.svg?logo=rust)](https://www.rust-lang.org/) [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) -A Rust terminal system monitor for CPU, memory, disks, network activity, processes, and host metadata. - -grainx is a pre-1.0 project. The repository documents the implemented behavior and the checks that run in CI; it does not publish unsupported runtime or benchmark numbers. +**Status:** Experimental CLI tool (v0.1.2, pre-1.0) under active development; CI verifies builds and tests on Linux and macOS. ## What it does -- Interactive terminal dashboard with Unicode/Braille charts. -- Local system collection through sysinfo: CPU, memory, disks, network counters, processes, OS, kernel, and uptime. -- Optional analytics: z-score anomaly detection, Pearson correlation, moving-average estimates, and a deliberately simple arithmetic formula evaluator. -- Adaptive refresh and frame skipping when CPU load is high. -- Optional HTTP metrics service with GET /health and GET /metrics. -- JSON and CSV snapshots from local or remote metrics. -- JSON configuration with environment-variable and CLI overrides. -- Shell completion generation for Bash, Elvish, Fish, PowerShell, and Zsh. +- Interactive terminal dashboard with Unicode/Braille CPU and memory charts, process inspection, and process termination. +- Local host resource collection via `sysinfo`: CPU, memory, disk usage, per-interval network I/O, processes, and host metadata. +- Adaptive refresh rate scaling and frame skipping under heavy system CPU load. +- Local HTTP metrics service (`GET /health` and `GET /metrics`) restricted to loopback interfaces. +- Local and remote JSON and CSV metric snapshot export without starting the TUI. -The term agent in this repository means the HTTP metrics process. It is not an AI or LLM agent. +The term *agent* in this repository refers to the HTTP metrics daemon process, not an AI or LLM agent. ## Quick start @@ -96,10 +92,12 @@ Process termination is subject to the operating system permissions of the user r ## Metrics Semantics -- **CPU Usage**: System-wide CPU utilization is calculated as the average utilization across all logical cores since the last refresh. The default refresh interval is 1 second (1000ms), which provides a balanced sampling window. -- **Memory Usage**: Physical memory utilization reported by the operating system, excluding swap. -- **Network I/O**: `network_rx_bytes` and `network_tx_bytes` are the bytes received and transmitted during the most recent sampling interval (a per-interval delta reported by `sysinfo`). They are not cumulative counters and are not rates. The TUI labels the same values as kilobytes for the last interval. -- **Sampling Interval**: By default, the system monitor samples state every 1000ms. This is configurable via `GRAINX_REFRESH_INTERVAL_MS`. Adaptive refresh can increase this interval (slowing down the sampling rate) up to 2000ms when system CPU usage exceeds the configured warning threshold (default 80%). +- **CPU Usage**: System-wide CPU utilization is calculated as the average utilization across all logical cores since the last refresh ([src/monitor.rs](src/monitor.rs)). +- **Memory Usage**: Physical memory utilization reported by the operating system, excluding swap ([src/monitor.rs](src/monitor.rs)). +- **Network I/O**: `network_rx_bytes` and `network_tx_bytes` are the bytes received and transmitted during the most recent sampling interval (a per-interval delta reported by `sysinfo`, not a cumulative counter or rate). The TUI displays this as `Network I/O: RX KB TX KB (last interval)` ([src/ui.rs](src/ui.rs), [src/network.rs](src/network.rs)). +- **Sampling Interval**: The default refresh interval is 500ms, configured in [dashboard_config.json](dashboard_config.json) and [src/config.rs](src/config.rs) (overrideable via `GRAINX_REFRESH_INTERVAL_MS` or `--refresh-interval-ms`). +- **Adaptive Refresh & Frame Skipping**: When enabled, the monitor scales target refresh dynamically based on rolling average CPU load: 250ms (<=50%), 500ms (>50%), 1000ms (>70%), and 2000ms (>90%), taking `adaptive_refresh.max(base_refresh)` ([src/performance.rs](src/performance.rs), [src/tui.rs](src/tui.rs)). If CPU load exceeds 95%, the dashboard skips rendering frames ([src/performance.rs](src/performance.rs)). +- **Warning Thresholds**: CPU warning threshold defaults to 80.0% and memory warning threshold defaults to 85.0% ([src/config.rs](src/config.rs)), driving alert highlights in the TUI ([src/ui.rs](src/ui.rs)) and high-load alerts ([src/monitor.rs](src/monitor.rs)). ## Demos @@ -152,8 +150,10 @@ Scope notes: ## Limitations -- **Security**: The HTTP agent has no TLS, authentication, or rate limiting. It refuses any non-loopback bind address at runtime, and `src/agent.rs` tests that `0.0.0.0`, `::`, and ordinary interface addresses are rejected. Loopback does not isolate users or processes on the same host, and remote metrics access is out of scope for this version. -- **Completeness**: Network and disk I/O are aggregates and do not currently drill down into per-socket or per-file statistics. +- **Security**: The HTTP agent has no TLS, authentication, or rate limiting. It refuses any non-loopback bind address at runtime, and `src/agent.rs` tests that `0.0.0.0`, `::`, and ordinary interface addresses are rejected. Loopback does not isolate users or processes on the same host; remote metrics access requires placing an authenticated transport in front of the agent. +- **Completeness**: Network and disk I/O are aggregates and do not drill down into per-socket or per-file statistics. +- **Formula Evaluator**: `evaluate_metric_formula` evaluates whitespace-separated tokens strictly left-to-right with no operator precedence or parentheses ([src/analytics.rs](src/analytics.rs)). +- **Interactive TUI**: The `monitor` command requires an interactive terminal (TTY) and exits with an error in headless environments ([src/tui.rs](src/tui.rs)). - **OS Support**: CI tests Linux and macOS on stable Rust. Windows is not verified and is not covered by the CI matrix. ## Verification diff --git a/docs/architecture.md b/docs/architecture.md index c97582d..ab26d52 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -33,5 +33,5 @@ The HTTP agent is a separate process path that exposes one health endpoint and o - The agent uses HTTP with no authentication, TLS, or rate limiting. - The formula evaluator is a prototype with whitespace-separated, left-to-right arithmetic; it is not a full expression language. -- CI currently verifies Linux only. Cross-platform behavior still needs a release validation matrix. +- CI verifies Linux and macOS. Windows is not covered by the CI matrix. - Process termination follows the permissions and platform behavior of the user running the process.