# dgxtop：偽のゼロを表示しない GPU ターミナルモニターの設計

dgx-spark-overview.webp1909×961

## 書き直した理由

バージョン 1 は UI ループ内でハードウェアをサンプリングしていたため、ドライバー呼び出しが遅くなると画面全体が固まりました。データ、履歴、UI 状態を 1 つの共有構造体に入れ、thermal zone の名前と走査順で CPU 温度を選び、読み取れない値を 0 と表示していました。v2 の仕様ではこうした問題を 10 項目挙げ、それぞれに設計上の回答を用意しています。

実装に先立って、40 項目の要件、15 の作業パッケージ、40 の受け入れケースを仕様にまとめました。その後、固定した core の契約に従い、8 crate の Rust workspace として実装しています。Rust は約 157,000 行、テストは 1,373 件です。

## 表示できるもの

概要、GPU、履歴、設定の 4 つのタブがあります。以下は実際にテストした 2 台のスクリーンショットです。

workstation-overview.webp1906×966

dgx-spark-gpu.webp1922×960

workstation-gpu.webp1906×976

dgx-spark-history.webp1906×956

workstation-history.webp1907×971

dgx-spark-settings.webp1916×957

## 6 つの構成要素、2 つの経路

数値はデータ経路を通り、利用者の意図は制御経路を通ります。Manager が唯一の書き込み主体です。Store の書き込み権限とプロセス操作の port を持つのは Manager だけなので、Viewer と Controller はデータを変更することも、シグナルを送ることもできません。

10 個の表示モジュールはコンパイル時に登録され、自分の view model と画面領域だけを受け取ります。あるモジュールが panic してもモジュールエラーとして隔離され、サンプリングまで巻き込んで停止させません。

## ドライバーが止まっても画面は動く

タイムアウトは結果が遅いことを示すだけで、呼び出しを取り消しません。ベンダーのライブラリ内で停止したスレッドを安全に止めることはできないため、各 live adapter は専用の常駐子プロセスで動きます。同じ実行ファイルを adapter host モードで起動し、長さを先頭に付けた最大 1 MiB の JSON フレームを匿名パイプで親プロセスと交換します。

期限を超えた host は縮退状態になります。3 回連続で失敗するとサーキットブレーカーが開き、再試行は 1、2、4…60 秒の間隔でバックオフします。host の交換は回収（reap）が完了してから行い、回収できない host は隔離します。同時に存在する数は最大 8 個です。

親プロセスは固定数のスレッドを使い、async runtime は使いません。ネットワーク I/O がなく、spawn_blockingを使っても、取り消せない同じ呼び出しが future の背後に隠れるだけだからです。管理対象の全データで 256 MiB の予算を共有し、各キューには件数とバイト数の両方の上限を設けます。有界 channel が数えるのはメッセージ数で、バイト数ではありません。

## 平均せず、出所を説明する

Linux は同じセンサーを複数のインターフェースで公開することがあります。ラベルだけでは何を測るかも確定せず、temp1 が CPU とは限りません。dgxtop はまず、ホスト、起動、エンティティ、指標、範囲で構成する metric key により読み取り値の意味を定め、同じ key の値だけを比較します。

別の出所への切り替えには、3 回連続での優位と最低 5 秒の経過を必要とし、値がセンサー間を行き来するのを防ぎます。読み取り状態、データ種別、品質、鮮度は単一の信頼度スコアにまとめず、4 つの独立した軸として保ちます。

## 正確な履歴

レートは 2 つの u64 カウンターの差分を、CLOCK_BOOTTIMEによる実経過時間で割った値です。この時計はサスペンド中も進みます。カウンターのリセット、再起動、出所の変更があれば新しい区間を開始し、負のレートや架空のレートを作りません。

1 分単位の集計では、その区間のどの瞬間にバイトが流れたかは分かりません。そのため総量には時間窓の内側に完全に収まる区間だけを含めます。分の境界をまたぐ区間は正確な bridge として保持し、1 回だけ数え、比例配分はしません。

ゲージ値は時間で重み付けし、出所の鮮度期限までだけ有効とします。欠測区間は欠測のまま残します。履歴はhistory.sqlite3 に 7 日間、最大 1 GiB 保存するため、以前の実行時の記録も表示できます。アーカイブへの書き込みはsynchronous=NORMAL、操作監査は FULLを使います。グラフの最後の 1 秒が失われることは許容しても、シグナル送信の記録が失われることは許容しません。

## 安全策を備えたプロセス終了

監視ツールにとって、誤ったプロセスを終了することは最悪の失敗です。そのため終了操作はProcessKey（ホスト、起動、PID namespace、PID、開始時刻）を対象に、監査付きの 2 段階で行います。行番号や PID だけを対象にはしません。

準備段階で利用者を確認し、root セッション、PID 1、dgxtop 自身とその host を拒否します。pidfd を開いてから /procで識別情報を再確認します。確認には 10 秒間有効な一度限りのトークンを使います。シグナル送信前にsynchronous=FULLで intent を書き込み、準備段階から保持している pidfd 経由で送信するため、再利用された PID を誤って終了させません。

結果はシグナル送信済みと終了を観察済みを分けて示します。intent の永続化後、結果の記録前にクラッシュした場合は不明と記録し、再送しません。データベースのコミットとシステムコールに共通のトランザクションはないため、保証できるのは「高々 1 回」です。SIGKILL は actions.allow_forceを設定しない限り無効で、--read-only はすべての操作を無効にします。

## 資源予算と過負荷

dgxtop が管理するすべての割り当ては、用途別に区分した共通の 256 MiB の予算から差し引きます。これは割り当てを許可する上限で、メモリの実測値ではありません。アロケーターのオーバーヘッド、スレッドのスタック、NVIDIA ライブラリは別途加わるため、仕様ではプロセスツリー全体に 384 MiB の目標を別に設けています。

過負荷時には、dgxtop は精度を黙って落とすのではなく、縮退状態を明示します。圧迫状態では任意の作業を止め、描画を最大 2 fps にします。抑制状態ではクエリを制限し、サンプリング周期を延ばし、バナーに設定値と実際の値を併記します。回復時は正常な状態が 30 秒続くごとに 1 段階ずつ戻し、失われたサンプルを補間しません。

## 境界と検証

workspace は 8 crate で構成されます。各実装 crate が依存するのはdgxtop-core だけで、すべてを参照できるのは組み立ての起点だけです。CI スクリプトが cargo metadata を読み、実装 crate が別の実装 crate に依存するとビルドを失敗させます。core 自体は NVML、libc、SQLite、UI に依存しません。

フォーマット、lint、1,373 件のテスト（aarch64 では 1,372 件）、依存関係の境界、実機テストは、RTX 5080 と RTX 3060 を搭載する Debian 13 ワークステーションと DGX Spark の両方で合格しています。受け入れ報告は 40 ケースを追跡しており、14 件が合格、24 件が未実行（多くは明示的な起動を要するエンドツーエンドテスト）、2 件が 30 分のベンチマーク 3 回と 72 時間の連続稼働テストを待っています。これらがそろうまでは、どのプラットフォームも受け入れ検証済みとはせず、性能値も目標値のままです。

## 設計上のトレードオフ

• adapter ごとにスレッドではなくプロセスを使う。常駐メモリと IPC のコストは増えますが、ドライバーが停止しても他の処理を固めません。
• async runtime ではなく、固定スレッドと crossbeam channel を使う。導入する理由となるネットワーク I/O がないためです。
• プラグインではなく、コンパイル時に登録する。adapter と表示モジュールのために不安定な Rust ABI を使う必要がなく、新たな攻撃面も増やしません。
• 平均を取らず、競合を表示する。画面は多少整わなくても、どのセンサーも報告していない数値は出しません。
• 再試行せず、シグナルは高々 1 回にする。結果が不明なら、不明と表示します。
• 変化したときだけ、最大 4 fps で再描画する。監視に 60 fps は不要です。遅いターミナルでも入力をブロックしてはいけません。

## 関連資料

• ソースコードと README（English · 繁體中文 · 日本語）（外部サイト）
• 仕様（繁体字中国語）（外部サイト）
• 最新リリース：インストールスクリプトとバイナリ（外部サイト）
• 実装判断 D-01～D-61（外部サイト）
• 検証報告と証拠（外部サイト）