Metadata-Version: 2.4
Name: kernstat
Version: 0.1.1
Summary: Linux kernel statistics CLI tool
Keywords: linux,kernel,system,monitoring,cli
Author: Wai Hlyan Min Thein
Author-email: Wai Hlyan Min Thein <waihlyanminthein@gmail.com>
License-Expression: GPL-3.0-or-later
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: System :: Monitoring
Requires-Dist: click>=8.0
Requires-Dist: rich>=15.0.0
Requires-Python: >=3.12
Project-URL: Repository, https://github.com/WaiHlyanMinThein17/kernstat
Description-Content-Type: text/markdown

# kernstat

![CI](https://github.com/WaiHlyanMinThein17/kernstat/actions/workflows/ci.yml/badge.svg)
![License](https://img.shields.io/badge/license-GPL--3.0-blue)
![Python](https://img.shields.io/badge/python-3.14+-blue)
![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)

Lightweight Linux system statistics CLI built directly on `/proc` and `/sys`
interfaces. `kernstat` reports CPU, memory, disk, network, and per-process
metrics without external monitoring daemons or subprocess wrappers, with both
human-readable and JSON output modes for scripting and automation. It also
includes a live updating terminal dashboard.

---

## Basic usage

Show CPU usage:

```bash
kernstat cpu
```

```
CPU Usage:    12.4%
```

Show memory statistics:

```bash
kernstat memory
```

```
Memory
  Total:      7.62 GB
  Used:       4.11 GB
  Available:  3.51 GB
  Usage:      53.94%
```

Show full system report:

```bash
kernstat report
```

```
CPU Usage:    10.8%

Memory
  Total:      7.62 GB
  Used:       4.09 GB
  Available:  3.53 GB
  Usage:      53.67%

Disk
  Total:      238.47 GB
  Used:       121.84 GB
  Free:       116.63 GB
  Usage:      51.09%
  Reads:      0.0/sec
  Writes:     2.0/sec

Network (wlp1s0)
  Download:   4.82 KB/s
  Upload:     0.31 KB/s
```

Show statistics for a specific process:

```bash
kernstat proc 1
```

```
Process 1
  Name:       systemd
  State:      S (sleeping)
  Threads:    1
  Memory:     14.96 MB
  CPU Usage:  0.0%
  Command:    /usr/lib/systemd/systemd --switched-root --system
```

Run the live dashboard:

```bash
kernstat dashboard
```

```
          kernstat live dashboard
┌──────────────────┬──────────────────────────────┐
│ Metric           │ Value                        │
├──────────────────┼──────────────────────────────┤
│ CPU              │ 23.4%                        │
│ Memory           │ 4.85 / 6.94 GB (69.8%)       │
│ Disk             │ 23.08 / 34.42 GB (67.0%)     │
│ Disk IO          │ 0.00 reads/s | 2.00 writes/s │
│ Network (wlp1s0) │ ↓ 4.82 KB/s | ↑ 0.31 KB/s    │ 
└──────────────────┴──────────────────────────────┘
    Updated 14:52:31 • Press Ctrl+C to quit
```

The dashboard refreshes continuously until interrupted with Ctrl+C. Set the
refresh interval with `--interval`, for example `kernstat dashboard --interval 2`.

JSON output for scripting:

```bash
kernstat report --format json
```

```json
{
  "cpu": {
    "cpu_percent": 10.8
  },
  "memory": {
    "total_gb": 7.62,
    "available_gb": 3.53,
    "used_gb": 4.09,
    "percent": 53.67
  },
  "disk": {
    "io": {
      "reads_per_sec": 0.0,
      "writes_per_sec": 2.0,
      "read_bytes_per_sec": 0.0,
      "write_bytes_per_sec": 1024.0
    },
    "space": {
      "total_gb": 238.47,
      "free_gb": 116.63,
      "used_gb": 121.84,
      "percent": 51.09
    }
  },
  "network": {
    "rx_bytes_per_sec": 4935.68,
    "tx_bytes_per_sec": 317.44,
    "rx_kb_per_sec": 4.82,
    "tx_kb_per_sec": 0.31
  }
}
```

---

## Installation

Install from PyPI:

```bash
pip install kernstat
```

Run the CLI:

```bash
kernstat report
```

For development:

```bash
git clone https://github.com/WaiHlyanMinThein17/kernstat.git
cd kernstat
uv sync
```

---

## Commands

| Command | Description |
|---------|-------------|
| `kernstat cpu` | CPU usage percentage |
| `kernstat memory` | Memory usage statistics |
| `kernstat disk` | Disk I/O and space statistics |
| `kernstat network` | Network I/O statistics |
| `kernstat proc <pid>` | Statistics for a specific process |
| `kernstat report` | Full system report |
| `kernstat dashboard` | Live updating system metrics dashboard |

All metric commands accept `--format json` for structured output. The
dashboard accepts `--interval` to set the refresh rate in seconds.

---

## Configuration

kernstat reads optional configuration from
`~/.config/kernstat/config.toml`, or from
`$XDG_CONFIG_HOME/kernstat/config.toml` if that environment variable is set.

```toml
[kernstat]
interval = 0.5
format = "json"
```

Available settings:

| Setting | Type | Default | Description |
|---------|------|---------|-------------|
| `interval` | float | 0.1 | Sampling interval in seconds for rate calculations |
| `format` | string | text | Default output format, either text or json |

Command line flags always override configuration file values. If no config
file exists, built-in defaults are used. See
[config.example.toml](config.example.toml) for a documented example you can
copy to get started.

---

## Design notes

**Direct `/proc` and `/sys` parsing**

`kernstat` reads Linux kernel interfaces directly instead of shelling out to
tools like `top`, `free`, or `iostat`. This avoids subprocess overhead, removes
dependencies on external utilities, and keeps the implementation portable across
minimal Linux environments and containers. Parsing kernel interfaces directly
also provides predictable structured data and exposes how Linux system metrics
are actually represented internally.

**Sampling with two readings**

CPU and network usage are calculated from differences between two cumulative
kernel readings over a short interval. Linux counters in `/proc` continuously
increase since boot, so a single reading cannot represent utilization or
throughput by itself. Taking two samples and calculating the delta produces
accurate rates such as CPU utilization percentages and network transfer speeds.

**JSON output for automation**

All commands support structured JSON output in addition to human-readable
terminal output. This allows `kernstat` to integrate cleanly with shell
scripts, monitoring pipelines, CI systems, and other automation tooling.
The JSON mode provides stable machine-readable output while preserving a
concise CLI experience for interactive use.

---

## Contributing

Contributions, bug reports, and suggestions are welcome. See
[CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.

Run tests:

```bash
uv run pytest
```

Run linting:

```bash
uvx ruff check src tests
```

---

## License

`kernstat` is released under the [GPL-3.0 license](LICENSE).