# Rsysstat

**Repository Path**: openeuler/Rsysstat

## Basic Information

- **Project Name**: Rsysstat
- **Description**: 本项目已经迁移至 AtomGit  || This project has been migrated to AtomGit || Linked: https://atomgit.com/openeuler/Rsysstat
- **Primary Language**: Unknown
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 1
- **Created**: 2025-11-12
- **Last Updated**: 2025-12-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: sig-MCP-Tools-Ecosystem

## README

# Notice: This project has been migrated to [AtomGit](https://atomgit.com/openeuler/Rsysstat)

# 通知: 本项目已经正式迁移至 [AtomGit](https://atomgit.com/openeuler/Rsysstat) 平台

# Rsysstat

Rsysstat 是对原生 sysstat 工具集的 Rust 语言重新设计与实现项目，采用现代化的 Rust workspace 架构，在保持与上游完全一致的命令行接口、输出格式与行为的前提下，引入 Rust 的内存安全与现代工程实践。

## 项目目标
- 兼容性优先：命令行参数、输出内容、退出码与错误信息与原生 sysstat 完全一致。
- 重新设计架构：采用 Rust workspace 架构，模块化设计，各工具独立编译和分发，共享核心库。
- 命名规范：为避免与系统原生命令冲突，各子工具使用 `rs-` 前缀命名：`rs-sar`、`rs-sadf`、`rs-sadc`、`rs-iostat`、`rs-mpstat`、`rs-pidstat` 等。
- 渐进式开发：先完成核心工具，再扩展到完整工具集。

## 工具优先级
- 核心工具：`rs-sadc`（数据收集器）、`rs-sadf`（数据格式化器）、`rs-sar`（系统活动报告器）
- 系统监控：`rs-iostat`（I/O 统计）、`rs-mpstat`（多处理器统计）、`rs-pidstat`（进程统计）
- 扩展工具：`rs-cifsiostat`（CIFS I/O 统计）、`rs-tapestat`（磁带统计）
- 辅助脚本：`rs-sa1`（数据收集脚本）、`rs-sa2`（报告生成脚本）

## 兼容性与行为约束
- 参数解析：支持并严格对齐上游所有选项、短/长参数、互斥与默认值。
- 输出格式：列名、列宽、单位、舍入/对齐、时间戳格式与本地化行为严格一致。
- 退出码：错误分类与退出码与上游一致；错误信息文本对齐原生实现。
- 数据格式：二进制数据文件格式与原生 sysstat 完全兼容，支持互读互写。
- 系统调用：遵循上游对于 `/proc`、`/sys` 文件系统的访问策略与字段解析规则。
- 平台范围：以 Linux 为主，依赖 `/proc` 和 `/sys` 文件系统；非 Linux 平台不承诺兼容。

## 代码组织
本项目以 Rust workspace 组织，每个工具为独立二进制 crate，共享基础库以统一访问 `/proc`、数据格式与兼容逻辑。

```
Rsysstat/
  Cargo.toml                  # workspace 声明
  core/                       # 核心库模块
    c_lib/                    # C库绑定：FFI 接口与底层函数
    comms/                    # 通用模块：活动类型定义、数据读写协议
    stats/                    # 统计模块：CPU、内存、磁盘、网络等统计处理
    utils/                    # 工具模块：格式化、文件操作、辅助函数
    lib.rs                    # 核心包入口，重新导出所有子模块
  bin/                        # 独立的二进制包
    sar/
      src/main.rs             # rs-sar 系统活动报告器实现
    sadf/
      src/main.rs             # rs-sadf 数据格式化器实现
    sadc/
      src/main.rs             # rs-sadc 数据收集器实现
    iostat/
      src/main.rs             # rs-iostat I/O统计工具实现
    mpstat/
      src/main.rs             # rs-mpstat 多处理器统计工具实现
    pidstat/
      src/main.rs             # rs-pidstat 进程统计工具实现
    cifsiostat/
      src/main.rs             # rs-cifsiostat CIFS I/O统计工具实现
    tapestat/
      src/main.rs             # rs-tapestat 磁带统计工具实现
    sa/                       # 脚本包
      src/
        sa1.rs                # rs-sa1 数据收集脚本实现
        sa2.rs                # rs-sa2 报告生成脚本实现
  factory/                    # 系统服务配置
    rsysstat.service          # 主服务文件
    rsysstat-collect.service  # 数据收集服务
    rsysstat-collect.timer    # 数据收集定时器
    rsysstat-rotate.service   # 日志轮转服务
    rsysstat-rotate.timer     # 日志轮转定时器
    rsysstat-summary.service  # 报告生成服务
    rsysstat-summary.timer    # 报告生成定时器
```

## 架构设计特点

- **模块化设计**：采用 Rust workspace 架构，核心库与各工具独立开发，便于维护和扩展。
- **数据格式兼容**：二进制数据文件格式与原生 sysstat 完全兼容，支持互读互写，确保平滑迁移。
- **系统调用封装**：优先使用 Rust 标准库进行文件 I/O，必要时通过 FFI 调用底层 C 库，保持对 `/proc` 和 `/sys` 的访问策略一致。
- **类型安全**：利用 Rust 的类型系统确保内存安全，避免数据竞争和内存泄漏。

## 构建与运行
- 系统要求：Linux（启用 `/proc` 和 `/sys`），Rust stable（建议安装 `rustup`）。
- 获取代码：
  - `git clone <repo-url>`
- 构建：
  - `cargo build --workspace --release`（构建所有工具）
  - `cargo build -p rs-sar --release`（构建特定工具）
- 运行示例（与原生保持一致的参数）：
  - `target/release/rs-sadc 1 10 /var/log/sa-rs/sa$(date +%d)`（收集 10 次数据，间隔 1 秒）
  - `target/release/rs-sar -u 1 5`（显示 CPU 使用率，间隔 1 秒，共 5 次）
  - `target/release/rs-sadf -d /var/log/sa-rs/sa01 -- -u`（从文件读取并显示 CPU 统计）
  - `target/release/rs-iostat -x 1 3`（显示扩展 I/O 统计）
  - `target/release/rs-mpstat -P ALL 1 2`（显示所有 CPU 统计）
  - `target/release/rs-pidstat -u 1 5`（显示进程 CPU 使用率）

## 兼容性验证

### 自动化测试框架

本项目实现了全面的测试验证框架，用于确保 Rust 实现与原生 sysstat 的输出**完全一致**。

**快速开始**：
```bash
# 编译工具
cargo build --all release

```

**主要特性**：
- ✅ 多种验证策略（字节级、行级、正则表达式）
- ✅ 智能处理动态数据（时间戳、设备名、PID）
- ✅ 详细的差异分析和可视化报告
- ✅ 预定义的测试套件（sar、sadf、iostat、mpstat、pidstat）

### 传统验证方法

- 快速对比：
  - `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)`
- 数据文件兼容性：使用原生 `sadc` 生成数据文件，用 `rs-sadf` 读取；使用 `rs-sadc` 生成数据文件，用原生 `sadf` 读取，验证双向兼容。
- Golden 测试：对标准输入参数组合生成上游输出快照，作为回归基准。
- 区域设置验证：在不同 `LC_ALL`/`LANG` 下验证格式与单位一致性。
- 退出码验证：构造错误场景（无权限/无数据文件/非法参数）比对退出码与错误文案。

## 开发指南

**快速概览**：
- 模块划分：`c_lib`（C库绑定）、`comms`（通用模块）、`stats`（统计处理）、`utils`（工具函数）、`format`（格式化输出）。
- 错误处理：统一使用 `Result`，细分为 I/O、解析、格式化、数据格式等错误域；所有错误文案对齐上游。
- 性能优化：避免重复系统调用，合理缓存 `/proc` 读取结果，控制分配，使用切片与零拷贝；保持输出兼容为前提。
- 日志与调试：调试日志默认关闭；任何日志不得污染标准输出（以免影响兼容性）。
- 代码风格：遵循 `rustfmt` 与静态检查（如使用 `clippy`）；风格检查不改变输出行为。

### 编译优化
- 使用 `cargo build --workspace --release` 编译所有包
- 使用 `cargo build -p <package-name> --release` 编译特定包
- 支持增量编译，提高开发效率

### 依赖管理
- 所有包都通过 workspace 统一管理
- 依赖关系清晰，无循环依赖：
  ```
  sysstat-c-lib (C库绑定包)
      ↓
  sysstat-comm (通用模块，依赖c-lib)
      ↓
  sysstat-stats (统计模块，依赖comm, c-lib)
      ↓
  sysstat-utils (工具模块，依赖comm, stats, c-lib)
      ↓
  sysstat-core (核心包，重新导出所有子包)
      ↓
  各个bin包 (依赖sysstat-core)
  ```
- 支持独立开发和测试各个模块

### 特性系统
- 核心包支持按需编译特定功能
- 通过 features 控制编译内容
- 支持开发和生产环境的不同配置

## 测试与基准（计划）
- 单元测试：格式化函数、选项解析、字段计算、数据文件读写。
- 端到端测试：对主工具的典型参数组合建立 Golden 快照。
- 性能基准：数据收集频率、格式化速度、大文件处理性能。
- 兼容性测试：与原生 sysstat 数据文件的互操作性验证。

## 平台与限制
- 仅支持 Linux；强依赖 `/proc` 与 `/sys` 文件系统。
- 在容器/最小系统上，根据可用的 `/proc` 字段自动降级但保持输出结构一致。
- 数据文件格式与原生 sysstat 完全兼容，支持互读互写。

## 系统服务配置

### 安装系统服务
```bash
# 复制服务文件到系统目录
sudo cp factory/rsysstat*.service /usr/lib/systemd/system/
sudo cp factory/rsysstat*.timer /usr/lib/systemd/system/
# 重新加载systemd配置
sudo systemctl daemon-reload

# 启用并启动服务
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
```

### 服务说明
- **rsysstat-collect**: 每10分钟收集一次系统数据
- **rsysstat-rotate**: 每天轮转日志文件
- **rsysstat-summary**: 每天生成系统报告

### 数据目录
- **数据存储**: `/var/log/sa-rs/`
- **配置文件**: `/etc/sysconfig/sysstat-rs`
- **可执行文件**: `/usr/lib64/sa-rs/`

## 迭代路线图
1. 完成 `rs-sadc` 的核心功能与数据文件格式兼容测试
2. 完成 `rs-sadf` 并建立基础公共库（`sysstat-core`）
3. 推进 `rs-sar`（选项解析、统计类型、输出布局）
4. 实现 `rs-iostat`、`rs-mpstat`、`rs-pidstat` 的统计与输出
5. 扩展到 `rs-cifsiostat`、`rs-tapestat`
6. 完成 `rs-sa1`、`rs-sa2` 脚本并进行整体验证

## 贡献指南
- 提交流程：Fork → 创建分支 → 开发与测试 → 发起 Pull Request。
- 代码要求：保证与上游兼容；附带必要测试与验证说明；不得引入影响输出的非必要变更。
- 讨论与评审：以兼容性与架构设计为最高优先级。

## 许可证
许可证将与上游保持兼容（具体细则将在初始化代码与依赖明确后补充说明）。

## 致谢
感谢原生 [sysstat](https://github.com/sysstat/sysstat) 项目与其维护者及贡献者。