Stallhunt

Stallhunt

Stallhunt 是一款以 Linux 为先的命令行性能排查工具。

仓库：https://github.com/guillem/stallhunt

top、htop、iotop、vmstat 和 iostat 等传统工具会展示测量结果。这些工具非常出色，但操作人员仍需回答更棘手的问题：

此刻究竟是什么在限制有效工作，谁在受影响，又很可能是谁造成的？

Stallhunt 旨在自动完成这一推理过程。

安装

要求：

• Linux 4.20 或更高版本，并已挂载 procfs；要给出压力判断，必须能读取 /proc/pressure 下的 PSI 文件，
• 从源代码构建需要 Rust 1.85 或更高版本。

有关 cargo install、发布版压缩包和支持矩阵，请参阅 docs/install.md。

从克隆的仓库安装：

cargo install --path .
stallhunt

直接运行 stallhunt 会执行默认的 10 秒排查。在终端中，它会显示紧凑的彩色报告；输出到管道或重定向（stallhunt | cat、>file、CI）时则保持为纯文本，不作更改。使用 --json 获取完整的结构化证据，使用 --verbose 将紧凑报告中折叠的注意事项展开为完整文本，或使用 --no-color（也可设置 NO_COLOR=1）关闭颜色而不改变布局：

stallhunt --json
stallhunt hunt --duration 30s
stallhunt hunt --verbose

捕获并回放经过规范化的观测结果：

stallhunt record --duration 10s --output incident.json
stallhunt replay incident.json
stallhunt redact incident.json --output incident.redacted.json

跟踪发现项的生命周期，直到达到限定数量的滚动窗口。在终端中，这会打开全屏 TUI（按 q 退出，使用方向键或 jk 选择，按 Enter/Space 显示或隐藏详情，使用 PageUp/PageDown/Home/End 滚动，按 h/? 查看帮助）。窗口尺寸达到 120×30 或更大时，还会在生命周期面板旁显示所选主机/cgroup 的六个进程角色列表；管道输出或 --json 仍为只追加的文本/JSON，并包含相同范围的角色信息：

stallhunt watch --interval 2s --count 3

通过 stdio 提供 Model Context Protocol 工具，让编码 Agent 能直接查询诊断结果——常驻采样器会持续维护近期压力的滚动视图，从而即时给出答案（对于 Claude Code：claude mcp add stallhunt -- stallhunt mcp；请参阅 docs/mcp-server.md）：

stallhunt mcp [--interval 2s] [--no-sampler]

仓库中包含用于 OpenAI 本地插件、适用于兼容客户端的 Linux MCPB 扩展以及官方 MCP Registry 元数据的源代码打包内容。这些软件包有意将诊断保留在本地，而不是将 Stallhunt 部署到被调查机器以外的机器上。请参阅 docs/directory-distribution.md。

生成 shell 补全脚本：

stallhunt completions bash > ~/.local/share/bash-completion/completions/stallhunt
stallhunt completions zsh > ~/.local/share/zsh/site-functions/_stallhunt

除非提供 --force，否则不会覆盖录制输出文件。10 秒排查是常规诊断方式；不足 1 秒的观测仅用于遥测冒烟测试，不会给出健康或压力判断。有关验证和选择性启用的验收命令，请参阅 docs/development.md。

核心理念

主要抽象是时间损失，而非利用率。

高利用率不一定意味着有问题。一台使用了 95% RAM 的机器可能完全健康。CPU 利用率为 70% 时，仍可能因调度器争用而导致对延迟敏感的工作受影响。因此，该项目关注进展受阻的证据：

• CPU 调度器压力，
• I/O 停顿，
• 内存压力/回收，
• 锁争用，
• 网络相关等待，
• 后续将支持更深入的阻塞链分析。

输出示例：

$ stallhunt

SYSTEM HEALTH: DEGRADED

1. CPU scheduling contention                         SEVERE
   Impact:    23.4% pressure during observation
   Victims:   postgres [4812], nginx [5120]
   Suspects:  rustc [9231], ffmpeg [9401]
   Confidence: high

   Evidence:
     CPU PSI some avg10:          23.4%
     run queue latency estimate:  elevated
     rustc CPU consumption:       735%
     postgres runnable delay:     3.8s / 10s

2. Block I/O contention                              MODERATE
   Device:    nvme0n1
   Victim:    postgres [4812]
   Suspect:   restic [7712]
   Confidence: medium

Memory: no significant pressure detected.
High memory occupancy alone is not treated as a bottleneck.

此输出是目标形态；项目将逐步实现。

产品原则

1. 诊断问题，而不只是展示信息。
2. 尽可能测量进展受阻的情况。
3. 区分观测与推断。
4. 为每项诊断展示证据。
5. 明确表达不确定性。
6. 即使没有 eBPF 也能发挥作用。
7. 开销足够低，能在承压系统上运行。
8. 将 Git 视为完整的项目记忆。

初始范围

首个实用版本面向 Linux，重点关注：

• CPU 调度争用，
• 内存压力，
• 块 I/O 压力，
• 在 Linux 提供足够证据时进行进程级归因，
• 在可行时按 cgroup/systemd 进行分组，
• 易于阅读的终端输出，
• 有版本标记的机器可读 JSON（1.0 之前的格式可能会演变），
• 有界观测窗口，
• 确定性的离线样例/回放分析。

后续版本可能会新增：

• 基于 eBPF 的非 CPU 运行时间分析，
• futex/锁争用，
• 系统调用/阻塞归因，
• 网络队列/套接字诊断，
• 依赖/等待图，
• 更丰富的 cgroup/容器分析。

仓库结构

.
├── AGENTS.md
├── CHANGELOG.md
├── Cargo.toml
├── LICENSE-APACHE
├── LICENSE-MIT
├── README.md
├── src/
│   ├── analysis.rs
│   ├── cgroup.rs
│   ├── cli.rs
│   ├── cpu.rs
│   ├── duration_us.rs
│   ├── io.rs
│   ├── main.rs
│   ├── mcp/
│   ├── memory.rs
│   ├── observe.rs
│   ├── psi.rs
│   ├── record.rs
│   ├── render.rs
│   ├── report.rs
│   ├── style.rs
│   ├── tui/
│   └── watch.rs
├── tests/
│   ├── cgroup_acceptance.rs
│   ├── cli.rs
│   ├── cpu_acceptance.rs
│   ├── io_acceptance.rs
│   ├── mcp.rs
│   ├── memory_acceptance.rs
│   └── fixtures/
│       ├── cpu/
│       └── proc-*
└── docs/
    ├── README.md
    ├── install.md
    ├── product.md
    ├── architecture.md
    ├── data-model.md
    ├── telemetry.md
    ├── inference-engine.md
    ├── cli-ux.md
    ├── security-privileges.md
    ├── testing.md
    ├── development.md
    ├── codex-workflow.md
    ├── experiments.md
    ├── references.md
    ├── roadmap.md
    ├── status.md
    ├── glossary.md
    └── decisions/

请先阅读 AGENTS.md，然后阅读 docs/README.md。

隐私政策

Stallhunt 读取有界的本地 Linux 遥测数据，不会自行通过网络发送这些数据。 MCP 客户端可能会根据各自的数据政策传输工具结果。有关数据、存储、共享、保留和联系方式的披露信息，请参阅完整的 Stallhunt 隐私政策。

许可证

根据你的选择，采用 MIT 或 Apache-2.0 双重许可。

当前状态

有关当前里程碑、已实现的功能、验证结果、已知限制以及下一项建议任务，请参阅 docs/status.md。计划的推进顺序仍见 docs/roadmap.md。