Stallhunt

Stallhunt

Stallhunt は Linux を優先したコマンドライン性能トリアージツールです。

リポジトリ：https://github.com/guillem/stallhunt

top、htop、iotop、vmstat、iostat などの従来のツールは測定値を表示します。どれも優れたツールですが、オペレーターは依然として、より難しい問いに答えなければなりません。

今、実際に有用な作業を制約しているものは何か、誰が影響を受けているのか、そしておそらく誰に責任があるのか？

Stallhunt は、その推論を自動化することを目指しています。

インストール

要件：

• procfs がマウントされた Linux 4.20 以降。圧力に関する判定には、/proc/pressure 以下の PSI ファイルを読み取れる必要があります。
• ソースからビルドする場合は Rust 1.85 以降。

cargo install、リリース tarball、サポート対象の一覧については、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 の 6 つのプロセス役割リストも表示します。パイプ出力または --json では、追記専用のテキスト／JSON 出力が維持され、同じスコープの役割情報も含まれます。

stallhunt watch --interval 2s --count 3

標準入出力経由で Model Context Protocol ツールを提供し、コーディングエージェントが診断結果を直接取得できるようにします。常駐サンプラーが直近の圧力をローリング表示するため、すぐに回答できます（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 を参照してください。

シェル補完を生成します。

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

--force を指定しない限り、記録ファイルの出力先は上書きされません。10 秒間の調査が通常の診断方法です。1 秒未満の観測はテレメトリーのスモークテストであり、正常または圧力の判定は行いません。検証方法とオプトイン方式の受け入れコマンドについては、docs/development.md を参照してください。

基本的な考え方

中心となる抽象概念は、使用率ではなく失われた時間です。

使用率が高いからといって、必ずしも問題があるとは限りません。RAM を 95% 使用しているマシンでも、まったく健全な場合があります。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 のプライバシーポリシー全文をご確認ください。

ライセンス

M以下のMITまたはApache-2.0のデュアルライセンスで、任意に選択できます。

現在の状況

現在のマイルストーンで実装されている機能、検証状況、既知の制限事項、次に推奨されるタスクについては、docs/status.mdをご確認ください。予定されている作業の順序は、docs/roadmap.mdに記載されています。