NCUE · UNIX 系統程式設計 · 2026 Spring

為受限 Linux 環境補上一組
可攜式診斷工具

單一 BusyBox-style binary,零外部依賴,提供 Process、Filesystem、Network 三類診斷 applet。

root@busybox:~#
BusyBox 1.36.1 3 applets C Table Raw JSON read-only
↗ GitHub 使用手冊

研究背景與動機

嵌入式系統診斷的三個根本困境

01

部署複雜度

top、df、ss 各自依賴獨立的動態函式庫。在容量受限的 rootfs 中,分別安裝的開銷往往超出可接受範圍,且版本相依管理複雜。

02

介面不一致

各工具的 CLI 介面與輸出格式差異顯著,難以整合至統一的自動化監控框架或 shell pipeline 流程中。

03

資源消耗過大

傳統互動式工具(如完整版 top)具有 ncurses 介面,在僅需擷取單次快照的場景下,啟動開銷與記憶體佔用明顯過大。

系統定位對比

比較項目 GNU Utils (top/ss/df) 標準 BusyBox BusyBox-Diag
外部相依性 高(多種 lib) 0 0
部署模式 分散安裝 單一 binary 單一 binary(Applet)
網路狀態支援 完整支援 缺乏(無 ss) 支援(被動解析)
Inode / Extent 分析 完整支援 僅基本空間 支援(statfs / fiemap)
JSON 輸出支援 不一致 不支援 完整支援(Table/Raw/JSON)

系統架構

嚴格四層分離,資料由核心向上單向流動

Kernel 介面層
系統真實狀態來源

直接讀取 Linux kernel 匯出的介面,不依賴任何私有 API 或外部函式庫。

/proc/net/tcp・udp /proc/[pid]/stat・status /proc/stat・meminfo・mounts statfs() syscall
libdiag 量測層
共用量測基礎設施(Zero-malloc 設計)

封裝 procfs 字串解析與 statfs 系統呼叫容錯,輸出強型別 C 結構體,讓三個工具不需各自重複實作底層解析邏輯。

diag_proc_t diag_fs_t diag_net_entry_t 串流 Callback 介面
工具邏輯層
三個 BusyBox Applet,各自實作分析 / 策略 / 過濾邏輯
diagfs — 空間/Inode 運算 → 健康閾值判定 ptop — Snapshot-Delta → Filter/Sort/Top-N diagnet — Streaming 串流解析 → 狀態/通訊埠篩選
展示層
BusyBox argv[0] Dispatch + isatty() 偵測

單一執行檔透過 symlink 分流至各 applet,isatty() 自動判斷輸出環境,pipe 時關閉 ANSI 色碼防止資料污染。

Table(人機互動 / ANSI 色彩) Raw(Shell Pipeline / grep / awk) JSON(自動化監控 / 結構化解析)

系統診斷工具集

三支工具,覆蓋系統診斷全場景

$ptop --output table -1 -n 1 PID PPID S RSS_KB UTIME STIME COMM 1 0 S 9100 1 0 sshd 20 0 S 1756 1 4 sh 148 136 S 48380 3 0 node 163 149 S 150532 424 147 node

ptop

行程資源分析器

  • Snapshot-Delta 架構:兩次快照差分,還原觀測區間真實 CPU 使用率
  • clock_gettime 避免 NTP 校正造成時間逆跳
  • VmRSS 直接反映實體記憶體壓力
  • 依 PID 配對前後快照(bsearch)
CLI Parse→ Collect prev→ sleep(d)→ Collect curr→ Delta Compute
$diagfs --output table / Filesystem snapshot: path = / fs_type = 0x794c7630 (unknown) total_kb = 1055762868 free_kb = 1046238932

diagfs

檔案系統健康檢測工具

  • 讀取 /proc/self/mounts,具備 Mount Namespace 感知
  • Inode 計算採無條件進位(Ceiling)
  • 整合 FIEMAP ioctl 觀察 Extent 佈局
  • 自動排除 proc 等 9 種虛擬檔案系統
量測層→ 分析層→ 策略層(閾值)→ 展示層
$diagnet --output table tcp 0.0.0.0 :22 -> 0.0.0.0 :0 LISTEN tcp 127.0.0.1 :34211 -> 0.0.0.0 :0 LISTEN tcp 172.17.0.2 :43288 -> 172.64.155.209 :443 TIME_WAIT tcp 127.0.0.1 :60110 -> 127.0.0.1 :34211 ESTABLISHED

diagnet

網路連線狀態監控器

  • 被動觀察 /proc/net/tcp,不主動發送封包
  • 串流 Callback 介面:空間複雜度 O(1)
  • 固定大小直方圖:TCP state 統計維持 O(1)
  • 正確處理 little-endian dotted-quad 還原
procfs→ libdiag callback→ Filter/Analyze→ Output

效能驗證

三個 benchmark case 全部通過,且均不慢於對照工具

效能比值 = 自製工具中位數時間 ÷ 對照組中位數時間。目標門檻 < 1.50(50% 差距內)。
200 次迭代取中位數,測試環境:Ubuntu 22.04 / Kernel 6.6 WSL2 / Intel i5-1135G7。

測試案例 工具 對照基準 效能比值 判定
M3-PTOP-01 ptop GNU top
0.868×
✓ PASS
M3-DIAGFS-01 diagfs GNU df
0.920×
✓ PASS
M3-DIAGNET-01 diagnet iproute2 ss
1.196×
✓ PASS

bar 長度代表比值相對於目標門檻 1.50 的位置;越短代表越快。ptop 與 diagfs 比值小於 1,代表自製工具快於對照組。

開始使用

三行指令,立即診斷

$git clone https://github.com/aloea4/BusyBox-Diag && cd BusyBox-Diag $scripts/bootstrap_busybox_diag.sh ~/workspace/busybox-1.36.1 $diagfs --output table / # 完成,立即開始診斷

困難與解決方案

開發過程中遭遇的三類設計難題

ptop

單次 procfs 讀取無法表示 CPU 使用率

/proc/[pid]/stat 的 utime、stime 是累積 jiffies,直接換算會讓閒置行程呈現虛高的使用率。

→ 採用 Snapshot-Delta 架構,擷取兩次快照的 jiffies 差值推導真實負載。以 bsearch() 依 PID 配對,穩定處理行程動態生滅。

diagfs

Docker 環境下掛載點視角落差

讀取 /proc/mounts 會取得宿主機掛載表,被容器特有的虛擬檔案系統污染,導致狀態誤判。

→ 改用 /proc/self/mounts,賦予程式 Mount Namespace Awareness,確保容器與實體機環境均能反映正確視角。

diagnet

/proc/net/tcp IP 位址位元組序錯誤

核心序列化時直接以十六進位印出 host-order 的 s_addr,在 x86 平台為 little-endian,導致 127.0.0.1 被誤讀為 1.0.0.127。

→ 實作 diag_ipv4_hex_le_to_str,解析為 unsigned int 後自 LSB 依序提取位元組還原,函式名稱保留 _le_ 後綴作為合約標記。

diagnet

--stats 模式記憶體無界成長

「全收集 → 排序 → 統計」流程在連線數龐大的主機上累積大量記錄,與嵌入式場景的記憶體預算衝突。

→ 串流導向處理(Stream-oriented),在 callback 階段直接累加計數,條件式跳過明細儲存,空間複雜度從 O(N) 退化至 O(1)。

ptop

互動式顯示與 shell pipeline 相容性衝突

ANSI 色彩與控制字元一旦被 pipe 傳遞至 awk,造成資料污染,破壞可解析性。

→ 以 isatty(STDOUT_FILENO) 自動偵測輸出環境,TTY 走 ptop_render_tty(),非 TTY 強制退回 batch 模式,兩種情境均兼顧。

diagnet

效能對照基準不對等導致比值失真

早期版本以 ss -tn 對照,但 ss 預設排除 LISTEN 與 TIME_WAIT,而 diagnet 列出所有狀態,工作量不對等,v2 比值達 1.95。

→ 自 v4 起改為 ss -tna / ss -tnua,並同步將 -O3 -flto 傳遞至 libdiag,修正後 v5 三組比值均降至 1.50 以內。