# block_perf_tools

**Repository Path**: cdevel/block_perf_tools

## Basic Information

- **Project Name**: block_perf_tools
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-16
- **Last Updated**: 2026-09-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# bdcheck — 通用块设备性能与健康检查工具

面向生产与客户环境的 Linux 块设备诊断工具。综合采集**系统 / 内核 / 驱动 / 硬件 /
存储栈**各层信息，输出人类可读的终端报告与机器可读的 JSON 归档。

仓库：https://gitlab.xpaas.lenovo.com/xcloud-storage/blk_perf_tools.git
（CLI 与 Python 包名仍为 **bdcheck**）。

核心设计约束：**诊断期间不给被诊断磁盘加任何 IO —— 读也不行。**
工具对客户数据零风险，可放心运行在含生产数据的机器上。

```mermaid
flowchart TB
    CLI["bdcheck CLI"]

    subgraph layers["采集分层 · 全部只读"]
        direction LR
        SYS["系统层<br/>OS / 内核<br/>CPU / NUMA<br/>sysctl"]
        DRV["驱动层<br/>模块版本<br/>参数<br/>dmesg"]
        HW["硬件层<br/>NVMe<br/>SMART<br/>identify"]
        BLK["块层<br/>队列参数<br/>调度器<br/>blk-mq"]
        STK["存储栈层<br/>文件系统<br/>cgroup IO<br/>IRQ / PCIe"]
        DYN["动态采样<br/>blktrace 旁路<br/>diskstats 差分<br/>eBPF 可选"]
    end

    CLI --> layers
    layers --> EXT["外部工具：nvme-cli · smartmontools · hdparm · blktrace · sg3_utils · lspci"]
```

## 怎么工作

一个 CLI 编排 7 步采集，全部只读。缺外部工具就跳过对应场景，不中断。

1. 系统/驱动 → 2. 拓扑 → 3. 存储栈 → 4. 块层队列 → 5. 硬件 identify/SMART
   → 6. IO 统计采样（`--no-perf` 关）→ 7. blktrace（`--no-trace` 关）
   → 健康汇总 → 写 JSON / 可选打包。

设计取舍：

- **零 IO 注入**：性能来自内核计数器差分；blktrace 走管道旁路；NVMe/SCSI 只发管理查询。
- **超时熔断**：管理命令卡住（含 D 状态）记超时后继续；同一设备第一条超时则跳过剩余查询。
- **只报事实**：SMART 失败、介质错误、PCIe 降速、文件系统 ≥95% 等；不给调优建议。
- **证据可校验**：`--collect-dir` 产出 `report.json`、`raw/`、`INDEX.md`、相对路径的 `MANIFEST.txt`。

退出码：`0` 成功，`2` 无有效设备，`3` 部分设备失败（结果仍可用），`4` JSON 写失败。
自动化只看退出码和 JSON。

## 交付与部署

| 形态 | 适用 | 说明 |
|---|---|---|
| 单文件二进制 | 客户机部署 (推荐) | `bash build.sh` 生成 `dist/bdcheck` (≈7.5MB ELF)，目标机无需装 Python，**不必放入 PATH**；上传当前目录或 `/tmp` 赋予权限后直接 `./bdcheck` 运行，用完即删 |
| pip 包 | 自己的运维机 | `pip install .`，提供 `bdcheck` 命令 |
| 直接运行 | 现场快速使用 | `python3 bdcheck.py`（需 Python 3.7+） |

无论哪种形态，nvme-cli/smartctl 等外部工具均不打包：目标机器缺哪个
就自动跳过对应采集场景，并在报告第 11 节与 JSON `collection_summary`
中显式汇报。

## 快速开始

```bash
# 安装 (Python 3.7+, 仅标准库)
pip install .            # 或 pip install -e . (开发模式)

# 全量静态采集 (所有顶层块设备) -> 终端报告 + JSON
# 默认全量检测: 硬件信息 + IO 统计采样 (10s) + blktrace 追踪 (10s)
bdcheck

# 指定设备 / 指定输出
bdcheck -d nvme0n1 -d sda -o /var/tmp/report.json

# 交付目录: 报告 + 全部命令原始输出 + 文件清单 (含 sha256)
bdcheck --collect-dir /tmp/bdcheck-$(date +%m%d)

# 采集并打 tar 包 (包内顶层目录与 tar 同名，避免多机解压覆盖)
bdcheck --collect-dir /tmp/bdcheck-out --tar

# 工具缺失的检测自动跳过; 也可手动禁用某项
bdcheck --no-trace   # 跳过 blktrace 追踪
bdcheck --no-perf    # 跳过IO 统计采样

# 仅列出可采集设备
bdcheck --list-devices
```

细节手册（命令行、字段、兼容性）仍放 `docs/`，不必先读完：

| 文档 | 内容 |
|---|---|
| [docs/USAGE.md](docs/USAGE.md) | 命令行手册、退出码、自动化集成 |
| [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md) | 部署、依赖分层、验证清单 |
| [docs/OUTPUT.md](docs/OUTPUT.md) | 终端报告与 JSON 字段、告警规则 |
| [docs/COMPATIBILITY.md](docs/COMPATIBILITY.md) | Python/内核/工具版本、设备覆盖 |
| [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) | 权限、缺工具、数据缺失 |

## 安全红线（不可妥协）

| 能力 | 状态 | 说明 |
|---|---|---|
| fio 基准测试 | **已移除** | 误改 rw 参数即毁客户数据，不存在开关 |
| hdparm -tT 读基准 | **已移除** | 会向设备发起大量介质读 |
| 任何负载注入 | **无** | blktrace 观测期间同样不注入负载 |
| blktrace | 保留 | 内核旁路监听已存在的请求，零新增 IO，管道模式不落盘 |
| NVMe ADMIN 查询 | 保留 | id-ctrl / smart-log / error-log 等，读日志页，不读用户数据 |
| SCSI/SATA 查询 | 保留 | smartctl -a / hdparm -I / sg_inq，INQUIRY/IDENTIFY/SMART 类 |

性能数据获取方式：两次采样 `/proc/diskstats`（内核计数器）做差分，
反映观测窗口内的**真实业务负载**。工具自身零 IO 注入。

## 采集内容

1. **系统层**：OS、内核版本与 cmdline、CPU/内存/NUMA 拓扑、关键 sysctl
2. **驱动层**：块相关内核模块（版本/引用计数/参数）、dmesg 中块设备告警
3. **硬件层**：NVMe identify/SMART/错误日志/固件日志/get-feature；SCSI/SATA 的
   smartctl JSON、hdparm -I、sg_inq
4. **拓扑层**：lsblk 树、udev 属性、mount 表、/proc/mdstat、DM 表、多路径、
   /dev/disk/by-{id,path,uuid} 映射
5. **存储栈层**：文件系统挂载与 df 容量/inode 使用率、XFS/ext4 运行统计、
   页缓存回写（Dirty/Writeback、bdi 统计）、cgroup IO（v1/v2）、
   存储相关中断向量、PCIe 链路速率/宽度与能力对比（低于能力记 degraded）、
   sar 历史归档（`--collect-dir` 时进证据包）
6. **块层**：/sys/block 队列参数（调度器、nr_requests、read_ahead_kb、
   max_sectors_kb、wbt、blk-mq 硬件队列数等）、diskstats 快照、in-flight
7. **IO 统计采样**（默认运行，`--no-perf` 禁用）：真实负载 IOPS/带宽/利用率/平均延迟 + SMART 前后快照对比
8. **动态追踪**（默认运行，`--no-trace` 禁用）：blktrace Q2C 延迟分布（p50/p90/p99/max，按读/写分开）；
   eBPF 能力自动探测（装有 bcc/bpftrace 时自动增强）

## 健康检查能力

工具自动汇总以下告警信号（第 10 节 + JSON `health_summary.warnings`）：

- NVMe：critical_warning、介质错误、可用备用空间低于阈值、寿命（percentage_used）、过温
- ATA/SCSI：SMART 整体 FAILED、重映射扇区/待定扇区/不可修复扇区非零
- 设备无响应：管理命令超时后跳过剩余查询（controller/device_unresponsive）
- 存储栈：文件系统/inode 使用率 ≥ 95%、PCIe 链路降速或缩宽（事实性对比 LnkCap）
- 系统类：dmesg 中块设备相关错误计数与样例

## 外部工具依赖

| 工具 | 必需性 | 缺失时行为 |
|---|---|---|
| Python 3.7+ | 必需 | — |
| nvme-cli | 建议 | NVMe 设备硬件信息缺失，报告中标注 |
| smartmontools | 建议 | SCSI/SATA 健康信息缺失 |
| hdparm | 建议 | SATA identify 缺失 |
| blktrace | 可选 | 缺失时自动跳过动态追踪 |
| sg3_utils | 可选 | SCSI INQUIRY 补充信息缺失 |
| util-linux (lsblk/udevadm) | 建议 | 拓扑信息降级 |
| dmsetup / multipathd | 可选 | DM/多路径信息缺失 |
| pciutils (lspci) | 可选 | 存储栈 PCIe 链路信息缺失（`pcie.available=false`） |
| sysstat | 可选 | 无 sar/sa 历史归档可检测与复制（不影响其他采集） |

外部工具缺失或版本过老时自动降级并在报告中标注；版本要求与设备类型
覆盖范围详见 [docs/COMPATIBILITY.md](docs/COMPATIBILITY.md)。

## 开发

```bash
pip install -e .
python -m pytest tests/          # 解析器单测；e2e 需 root
bash build.sh                    # 构建机: PyInstaller -> dist/bdcheck
```

| 文件 | 做什么 |
|---|---|
| `bdcheck.py` / `__main__.py` | 入口与 7 步编排 |
| `utils.py` | 跑命令、读文件、超时回收 |
| `sysinfo.py` / `topology.py` / `storagestack.py` / `blockqueue.py` / `devinfo.py` | 各层静态采集 |
| `perf.py` / `tracer.py` | diskstats 差分、blktrace 旁路 |
| `report.py` / `artifact.py` | 终端+JSON、raw 证据包 |

## License

MIT，见 [LICENSE](LICENSE)。