# dgxtop：設計一個不顯示假 0 的 GPU 終端監控工具

dgx-spark-overview.webp1909×961

## 為什麼重寫

第一版在 UI 迴圈裡採樣硬體，驅動呼叫一慢，整個畫面就凍住。它把資料、歷史與 UI 狀態放在同一個共用結構裡，依 thermal zone 的名稱與掃描順序挑 CPU 溫度，讀不到的值直接顯示成 0。v2 規格列出十個這類問題，並為每一個給出設計上的答案：

這次重寫先寫規格再寫程式：40 項需求、15 個工作包、40 個驗收案例。之後依固定的 core 契約建成八個 crate 的 Rust workspace，約 157,000 行 Rust，附 1,373 項測試。

## 畫面

四個分頁：總覽、GPU、歷史與設定。以下截圖來自實際測試的兩台機器。

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

## 六個元件、兩條路徑

每個數值走資料路徑，每個使用者意圖走控制路徑。Manager 是唯一的寫入者：只有它持有 Store 的寫入權與程序操作的 port，所以 Viewer 與 Controller 既不能改資料，也不能送訊號。

十個顯示模組在編譯期註冊，只拿到自己的 view model 與畫面區域。某個模組 panic 時，它被隔離成模組錯誤，不會連帶拖垮採樣。

## 驅動卡住，只拖住一個 host

逾時只代表結果晚到，並沒有取消那次呼叫：卡在廠商函式庫裡的執行緒無法安全地停下來。所以每個 live adapter 都在自己的常駐子程序裡執行（同一個執行檔以 adapter host 模式啟動），透過匿名管線與父程序交換附長度前綴、每個最多 1 MiB 的 JSON frame。

錯過期限的 host 會轉為降級；連續失敗 3 次後 circuit breaker 打開，重試依 1、2、4……60 秒退避。只有確實回收（reap）後才會換上新的 host；回收不了的 host 會被隔離，而且同時最多只有 8 個。

父程序只有固定數量的執行緒，不用 async runtime：這裡沒有網路 I/O，而 spawn_blocking 只會把同一個無法取消的呼叫藏到 future 後面。所有受管資料共用一份 256 MiB 預算，每條佇列除了筆數上限還有位元組上限，因為有界 channel 只數訊息，不數位元組。

## 可解釋的來源，不取平均

Linux 可能用好幾個介面暴露同一顆感測器，標籤也不保證它量的是什麼：temp1不一定是 CPU。dgxtop 先決定一筆讀值代表什麼（由主機、開機、實體、指標與範圍組成的 metric key），然後只比較同一個 key 的讀值。

要切換到另一個來源，必須連續勝出 3 次且至少經過 5 秒，數值不會在感測器之間來回跳。讀取狀態、資料種類、品質與新鮮度維持四個獨立的軸，不壓成一個信任分數。

## 精確的歷史

速率是兩個 u64 counter 的差值，除以CLOCK_BOOTTIME上的真實經過時間；這個時鐘在休眠期間也會繼續計時。counter 歸零、重新開機或來源切換時，會開始新的區段，而不是產生負的或捏造的速率。

一分鐘的彙總無法知道區間裡的位元組是在哪一刻流動的。所以時窗總量只計入完全落在窗內的區間；跨越分鐘邊界的區間以精確的 bridge 保存、只算一次，絕不按比例拆分。

gauge 依時間加權，數值只有效到來源的過期期限為止，空窗就留著空窗。歷史存在 history.sqlite3，保留 7 天、最多 1 GiB，之前執行的紀錄也會畫出來。封存使用 synchronous=NORMAL，操作稽核使用 FULL：圖表少了最後一秒可以接受，訊號的紀錄不見則不行。

## 受保護的程序終止

終止錯的程序，是監控工具最糟的失誤。所以終止是兩階段、有稽核的操作，對象是 ProcessKey（主機、開機、PID namespace、PID 與啟動時間），絕不是列號或單獨的 PID。

準備階段檢查使用者，拒絕 root 會話、PID 1、dgxtop 本身與它自己的 host，開啟 pidfd 後再透過 /proc重新核對身分。確認用的是 10 秒內有效的一次性 token。送訊號之前先以 synchronous=FULL寫入 intent，訊號再透過準備時就持有的 pidfd 送出，所以重用的 PID 不會被誤擊。

結果會分開標示已送出訊號與已觀察到結束。如果在 intent 落盤後、結果寫入前崩潰，該操作記為未知且絕不重送：資料庫 commit 與系統呼叫沒有共同的交易，所以誠實的保證是「至多一次」。SIGKILL 預設關閉，除非設定 actions.allow_force；--read-only 會關閉所有操作。

## 資源預算與過載

dgxtop 管理的每一筆配置都從同一本 256 MiB 的帳目扣除，並依用途分區。這些是准入上限，不是量到的記憶體：配置器開銷、執行緒堆疊與 NVIDIA 函式庫都另外計算，所以規格另外為整個程序樹訂了 384 MiB 的目標。

負載過高時，dgxtop 會看得見地降級，而不是默默失真。壓力狀態先停掉可選工作、繪製降到最多 2 fps；節流狀態限制查詢並拉長採樣週期，橫幅會同時顯示設定值與實際值。恢復時每 30 秒健康才退一級，遺失的採樣絕不補值。

## 邊界與驗證

workspace 有八個 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 個案例：12 個通過、24 個尚未執行（多半是需要另外啟動的端對端測試），4 個卡在正式 release、3 次 30 分鐘的效能基準與 72 小時 soak。在這些完成之前，沒有任何平台被宣稱為已驗收，效能數字也仍只是目標。

## 取捨

• 每個 adapter 一個程序，而不是一條執行緒。多付常駐記憶體與 IPC 的成本，換來卡住的驅動無法凍結其他任何東西。
• 固定的執行緒與 crossbeam channel，而不是 async runtime。沒有網路 I/O 值得引入它。
• 編譯期註冊，而不是外掛。adapter 與顯示模組不需要不穩定的 Rust ABI，也不增加攻擊面。
• 顯示衝突，而不是取平均。畫面沒那麼整齊，但絕不出現沒有任何感測器回報過的數字。
• 至多一次訊號，而不是重試。結果未知，就顯示未知。
• 只在變化時重繪，最多 4 fps。監控不需要 60 fps，而且慢的終端絕不能卡住輸入。

## 延伸閱讀

• 原始碼與 README（English · 繁體中文 · 日本語）（外部網站）
• 完整規格（繁體中文）（外部網站）
• 實作決策 D-01 到 D-57（外部網站）
• 驗證報告與證據（外部網站）