# Rsysstat

**Repository Path**: empire99200/Rsysstat

## Basic Information

- **Project Name**: Rsysstat
- **Description**: Rust’s guarantees in memory, type, and concurrency safety drive innovations in operating system security.
- **Primary Language**: Unknown
- **License**: GPL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2025-12-04
- **Last Updated**: 2025-12-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Rsysstat

Rsysstat is a Rust-based redesign and reimplementation of the native sysstat toolset, adopting a modern Rust workspace architecture. While maintaining complete consistency with upstream in terms of command-line interface, output format, and behavior, it introduces Rust's memory safety and modern engineering practices.

## Project Goals
- **Compatibility First**: Command-line arguments, output content, exit codes, and error messages are completely consistent with native sysstat.
- **Redesigned Architecture**: Adopts Rust workspace architecture with modular design, where each tool is independently compiled and distributed, sharing a core library.
- **Naming Convention**: To avoid conflicts with system native commands, all sub-tools use the `rs-` prefix: `rs-sar`, `rs-sadf`, `rs-sadc`, `rs-iostat`, `rs-mpstat`, `rs-pidstat`, etc.
- **Incremental Development**: Complete core tools first, then expand to the full toolset.

## Tool Priority
- **Core Tools**: `rs-sadc` (data collector), `rs-sadf` (data formatter), `rs-sar` (system activity reporter)
- **System Monitoring**: `rs-iostat` (I/O statistics), `rs-mpstat` (multi-processor statistics), `rs-pidstat` (process statistics)
- **Extended Tools**: `rs-cifsiostat` (CIFS I/O statistics), `rs-tapestat` (tape statistics)
- **Auxiliary Scripts**: `rs-sa1` (data collection script), `rs-sa2` (report generation script)

## Compatibility and Behavior Constraints
- **Argument Parsing**: Supports and strictly aligns with all upstream options, short/long arguments, mutual exclusions, and default values.
- **Output Format**: Column names, column widths, units, rounding/alignment, timestamp formats, and localization behavior are strictly consistent.
- **Exit Codes**: Error classification and exit codes are consistent with upstream; error message text aligns with native implementation.
- **Data Format**: Binary data file format is fully compatible with native sysstat, supporting mutual read/write operations.
- **System Calls**: Follows upstream access policies and field parsing rules for `/proc` and `/sys` filesystems.
- **Platform Scope**: Primarily Linux, depends on `/proc` and `/sys` filesystems; no compatibility commitment for non-Linux platforms.

## Code Organization
This project is organized as a Rust workspace, where each tool is an independent binary crate, sharing a base library for unified access to `/proc`, data formats, and compatibility logic.

```
Rsysstat/
  Cargo.toml                  # workspace declaration
  core/                       # core library modules
    c_lib/                    # C library bindings: FFI interfaces and low-level functions
    comms/                    # common modules: activity type definitions, data read/write protocols
    stats/                    # statistics module: CPU, memory, disk, network statistics processing
    utils/                    # utility module: formatting, file operations, helper functions
    lib.rs                    # core package entry, re-exports all sub-modules
  bin/                        # independent binary packages
    sar/
      src/main.rs             # rs-sar system activity reporter implementation
    sadf/
      src/main.rs             # rs-sadf data formatter implementation
    sadc/
      src/main.rs             # rs-sadc data collector implementation
    iostat/
      src/main.rs             # rs-iostat I/O statistics tool implementation
    mpstat/
      src/main.rs             # rs-mpstat multi-processor statistics tool implementation
    pidstat/
      src/main.rs             # rs-pidstat process statistics tool implementation
    cifsiostat/
      src/main.rs             # rs-cifsiostat CIFS I/O statistics tool implementation
    tapestat/
      src/main.rs             # rs-tapestat tape statistics tool implementation
    sa/                       # script package
      src/
        sa1.rs                # rs-sa1 data collection script implementation
        sa2.rs                # rs-sa2 report generation script implementation
  factory/                    # system service configuration
    rsysstat.service          # main service file
    rsysstat-collect.service  # data collection service
    rsysstat-collect.timer    # data collection timer
    rsysstat-rotate.service   # log rotation service
    rsysstat-rotate.timer     # log rotation timer
    rsysstat-summary.service  # report generation service
    rsysstat-summary.timer    # report generation timer
```

## Architecture Design Features

- **Modular Design**: Adopts Rust workspace architecture, with core library and tools developed independently for easy maintenance and extension.
- **Data Format Compatibility**: Binary data file format is fully compatible with native sysstat, supporting mutual read/write operations for smooth migration.
- **System Call Encapsulation**: Prioritizes Rust standard library for file I/O, uses FFI to call underlying C libraries when necessary, maintaining consistent access policies for `/proc` and `/sys`.
- **Type Safety**: Leverages Rust's type system to ensure memory safety, avoiding data races and memory leaks.

## Building and Running
- **System Requirements**: Linux (with `/proc` and `/sys` enabled), Rust stable (recommended to install `rustup`).
- **Get the Code**:
  - `git clone <repo-url>`
- **Build**:
  - `cargo build --workspace --release` (build all tools)
  - `cargo build -p rs-sar --release` (build specific tool)
- **Run Examples** (parameters consistent with native):
  - `target/release/rs-sadc 1 10 /var/log/sa-rs/sa$(date +%d)` (collect data 10 times, interval 1 second)
  - `target/release/rs-sar -u 1 5` (display CPU usage, interval 1 second, 5 times total)
  - `target/release/rs-sadf -d /var/log/sa-rs/sa01 -- -u` (read from file and display CPU statistics)
  - `target/release/rs-iostat -x 1 3` (display extended I/O statistics)
  - `target/release/rs-mpstat -P ALL 1 2` (display all CPU statistics)
  - `target/release/rs-pidstat -u 1 5` (display process CPU usage)

## Compatibility Verification

### Automated Testing Framework

This project implements a comprehensive testing and verification framework to ensure the Rust implementation's output is **completely consistent** with native sysstat.

**Quick Start**:
```bash
# Build tools
cargo build --all release

```

**Key Features**:
- ✅ Multiple verification strategies (byte-level, line-level, regular expressions)
- ✅ Intelligent handling of dynamic data (timestamps, device names, PIDs)
- ✅ Detailed difference analysis and visualization reports
- ✅ Predefined test suites (sar, sadf, iostat, mpstat, pidstat)

### Traditional Verification Methods

- **Quick Comparison**:
  - `diff -u <(sar -u 1 1) <(target/release/rs-sar -u 1 1)`
  - `diff -u <(iostat -x 1 1) <(target/release/rs-iostat -x 1 1)`
  - `diff -u <(mpstat -P ALL 1 1) <(target/release/rs-mpstat -P ALL 1 1)`
- **Data File Compatibility**: Use native `sadc` to generate data files, read with `rs-sadf`; use `rs-sadc` to generate data files, read with native `sadf`, verifying bidirectional compatibility.
- **Golden Tests**: Generate upstream output snapshots for standard input parameter combinations as regression benchmarks.
- **Locale Verification**: Verify format and unit consistency under different `LC_ALL`/`LANG` settings.
- **Exit Code Verification**: Construct error scenarios (no permission/no data file/invalid arguments) and compare exit codes and error messages.

## Development Guide

**Quick Overview**:
- **Module Division**: `c_lib` (C library bindings), `comms` (common modules), `stats` (statistics processing), `utils` (utility functions), `format` (formatting output).
- **Error Handling**: Unified use of `Result`, subdivided into I/O, parsing, formatting, data format error domains; all error messages align with upstream.
- **Performance Optimization**: Avoid repeated system calls, reasonably cache `/proc` read results, control allocation, use slices and zero-copy; maintain output compatibility as prerequisite.
- **Logging and Debugging**: Debug logging disabled by default; no logging should pollute standard output (to avoid affecting compatibility).
- **Code Style**: Follow `rustfmt` and static checks (e.g., using `clippy`); style checks do not change output behavior.

### Compilation Optimization
- Use `cargo build --workspace --release` to compile all packages
- Use `cargo build -p <package-name> --release` to compile specific packages
- Supports incremental compilation for improved development efficiency

### Dependency Management
- All packages are managed uniformly through workspace
- Clear dependency relationships with no circular dependencies:
  ```
  sysstat-c-lib (C library binding package)
      ↓
  sysstat-comm (common module, depends on c-lib)
      ↓
  sysstat-stats (statistics module, depends on comm, c-lib)
      ↓
  sysstat-utils (utility module, depends on comm, stats, c-lib)
      ↓
  sysstat-core (core package, re-exports all sub-packages)
      ↓
  Various bin packages (depend on sysstat-core)
  ```
- Supports independent development and testing of each module

### Feature System
- Core package supports on-demand compilation of specific features
- Control compilation content through features
- Supports different configurations for development and production environments

## Testing and Benchmarks (Planned)
- **Unit Tests**: Formatting functions, option parsing, field calculations, data file read/write.
- **End-to-End Tests**: Establish Golden snapshots for typical parameter combinations of main tools.
- **Performance Benchmarks**: Data collection frequency, formatting speed, large file processing performance.
- **Compatibility Tests**: Interoperability verification with native sysstat data files.

## Platform and Limitations
- **Linux Only**: Strongly depends on `/proc` and `/sys` filesystems.
- On container/minimal systems, automatically degrades based on available `/proc` fields while maintaining consistent output structure.
- Data file format is fully compatible with native sysstat, supporting mutual read/write operations.

## System Service Configuration

### Install System Services
```bash
# Copy service files to system directory
sudo cp factory/rsysstat*.service /usr/lib/systemd/system/
sudo cp factory/rsysstat*.timer /usr/lib/systemd/system/
# Reload systemd configuration
sudo systemctl daemon-reload

# Enable and start services
sudo systemctl enable rsysstat-collect.timer
sudo systemctl enable rsysstat-rotate.timer
sudo systemctl enable rsysstat-summary.timer
sudo systemctl enable rsysstat.service
sudo systemctl start rsysstat-collect.timer
sudo systemctl start rsysstat-rotate.timer
sudo systemctl start rsysstat-summary.timer
sudo systemctl start rsysstat.service
```

### Service Description
- **rsysstat-collect**: Collects system data every 10 minutes
- **rsysstat-rotate**: Rotates log files daily
- **rsysstat-summary**: Generates system reports daily

### Data Directories
- **Data Storage**: `/var/log/sa-rs/`
- **Configuration File**: `/etc/sysconfig/sysstat-rs`
- **Executables**: `/usr/lib64/sa-rs/`

## Iteration Roadmap
1. Complete core functionality of `rs-sadc` and data file format compatibility testing
2. Complete `rs-sadf` and establish base common library (`sysstat-core`)
3. Advance `rs-sar` (option parsing, statistics types, output layout)
4. Implement statistics and output for `rs-iostat`, `rs-mpstat`, `rs-pidstat`
5. Extend to `rs-cifsiostat`, `rs-tapestat`
6. Complete `rs-sa1`, `rs-sa2` scripts and perform overall verification

## Contributing Guide
- **Submission Process**: Fork → Create branch → Develop and test → Create Pull Request.
- **Code Requirements**: Ensure compatibility with upstream; include necessary tests and verification instructions; do not introduce unnecessary changes that affect output.
- **Discussion and Review**: Compatibility and architecture design are the highest priorities.

## License
The license will remain compatible with upstream (specific details will be added after code initialization and dependency clarification).

## Acknowledgments
Thanks to the native [sysstat](https://github.com/sysstat/sysstat) project and its maintainers and contributors.