🧩 inode-inspector

A minimal SRE-grade diagnostic CLI for Linux that detects real-world inode issues such as inode exhaustion, deleted-but-open files, and small-file hotspots — the ones that silently break systems before disks actually fill.

---

Quick Start

git clone https://github.com/<yourname>/inode-inspector.git
cd inode-inspector
python3 -m venv .venv && source .venv/bin/activate
pip install typer
export PYTHONPATH=src

Run your first check:

python -m inode_inspector.cli collect
python -m inode_inspector.cli analyze

What It Does

Rule	Detects	Why It Matters
R1-inode_full	Mounts with ≥95 % inode use (df -iT)	File creation will fail soon
R2-deleted_open	Deleted files still held open by a writer (lsof +L1)	Disk space never frees until process exits
R3-hotspot	Directories with >100 k files	Consumes inodes, slows listing, hurts backups

Simulate Problems

Try the built-in labs safely:

python -m inode_inspector.cli simulate deleted_open
# in another terminal:
python -m inode_inspector.cli collect && python -m inode_inspector.cli analyze

python -m inode_inspector.cli simulate inodes_full 50000
# watch inode usage climb; Ctrl+C to stop

All labs use temporary directories and clean themselves on exit.

Explain Findings

python -m inode_inspector.cli explain inode_full
python -m inode_inspector.cli explain deleted_open
python -m inode_inspector.cli explain hotspot

Each topic prints a short operational summary and first-response advice.

Example Output

$ python -m inode_inspector.cli analyze
INODE_WARNING: 3 deleted-but-open regular files (writers, ≥10 MiB).
Example PID 4276 FD 118 PATH /var/tmp/inode-lab.XXXXXX/log.txt size~16777216B
OK: no inode mount ≥ 95 % (excluding snap/squashfs)

Design Goals

• Minimal external dependencies (typer only)
• Works on any modern Linux (no privileged calls)
• Readable, auditable, SRE-friendly
• Extensible to Prometheus exporter or JSON API later

Next (Phase 2 Ideas)

• Add /metrics exporter for Prometheus
• Add JSON metrics mode
• Add --verbose explainers with shell-ready fix commands
• Package as pip module and publish on PyPI

© 2025 inode-inspector — built for educational & operational reliability.