Guider 指令參數完整指南

版本：3.9.9_250918 測試日期：2025-09-20 測試環境：Ubuntu Linux 6.14.0

目錄

1. 簡介
2. 基本用法
3. 全域參數說明
4. 指令分類
   • CONTROL - 控制類指令
   • LOG - 日誌類指令
   • MONITOR - 監控類指令
   • NETWORK - 網路類指令
   • PROFILE - 效能分析指令
   • TEST - 測試類指令
   • TRACE - 追蹤類指令
   • UTIL - 工具類指令
   • VISUAL - 視覺化指令
5. 常用指令詳解
6. 實用範例

簡介

Guider 是一個強大的系統效能分析和監控工具，提供了 183 個指令，涵蓋了從進程監控、效能分析到視覺化等多個方面。本指南提供了所有指令的完整參數說明和使用範例。

基本用法

# 基本語法（安裝後）
guider COMMAND [OPTIONS] [--help]

# 直接執行（未安裝）
python3 guider/guider.py COMMAND [OPTIONS] [--help]

# 查看幫助
guider --help

# 查看特定指令的幫助
guider COMMAND --help

# 範例
guider top --help

全域參數說明

以下是 Guider 中常用的全域參數，大多數指令都支援這些參數：

指令分類

CONTROL - 控制類指令

控制類指令用於管理和控制系統進程、資源限制等。

LOG - 日誌類指令

日誌類指令用於收集和分析各種系統日誌。

MONITOR - 監控類指令

監控類指令提供即時系統監控功能。

NETWORK - 網路類指令

網路類指令提供網路相關功能。

PROFILE - 效能分析指令

效能分析指令用於記錄和分析系統效能。

TEST - 測試類指令

測試類指令提供系統壓力測試功能。

TRACE - 追蹤類指令

追蹤類指令提供系統追蹤功能。

UTIL - 工具類指令

工具類指令提供各種實用功能。

VISUAL - 視覺化指令

視覺化指令將數據轉換為圖表。

常用指令詳解

top 指令詳解

top 是最常用的系統監控指令，提供豐富的參數選項：

啟用選項 (-e)

# 啟用 affinity 顯示
guider top -e a

# 啟用多個選項
guider top -e "aTmn"

可用選項：

• a: affinity (CPU 親和性)
• A: secAttr (安全屬性)
• b: block (阻塞統計)
• B: bar (條形圖)
• c: cpu (CPU 統計)
• C: compress (壓縮)
• d: disk (磁碟統計)
• D: DWARF (調試信息)
• e: encode (編碼)
• E: exec (執行)
• f: float (浮點數顯示)
• F: wfc (等待文件完成)
• G: cgroup (Cgroup 信息)
• h: sigHandler (信號處理器)
• H: sched (調度信息)
• i: irq (中斷統計)
• I: elastic (彈性搜索)
• k: peak (峰值)
• K: cgroupRoot (Cgroup 根)
• l: threshold (閾值)
• L: cmdline (命令行)
• m: mem (記憶體統計)
• M: min (最小統計)
• n: net (網路統計)
• N: namespace (命名空間)
• o: oomScore (OOM 分數)
• O: iosched (I/O 調度器)
• p: pipe (管道)
• P: perf (性能計數器)
• q: quit (自動退出)
• Q: group (群組信息)
• r: report (報告)
• R: reportFile (報告文件)
• s: stack (堆疊)
• S: pss (PSS 記憶體)
• t: thread (線程)
• T: total (總計)
• u: uss (USS 記憶體)
• U: unit (單位)
• w: wss (WSS 記憶體)
• W: wchan (等待通道)
• x: fixTarget (固定目標)
• X: exe (執行檔路徑)
• Y: delay (延遲)

停用選項 (-d)

# 停用 CPU 統計
guider top -d c

# 停用多個選項
guider top -d "cmn"

排序選項 (-S)

# 按 CPU 使用率排序
guider top -S c

# 按記憶體排序，顯示大於 500MB 的進程
guider top -S m:500

# 按記憶體排序，顯示小於 10MB 的進程（升序）
guider top -S "m:<10" -q ORDERASC

排序鍵：

• c: CPU 使用率
• m: 記憶體 (RSS)
• p: PID
• N: 進程名稱
• b: 阻塞時間
• w: wfc (等待文件完成)
• n: 新進程
• f: 文件數
• r: 運行時間
• s: swap
• e: 執行時間
• P: 優先級
• C: 上下文切換
• o: OOM 分數

環境變量選項 (-q)

# 顯示命令行
guider top -q CMDLINE

# 設定 OOM 調整值
guider top -q OOMADJ:-1000

# 只顯示 Android 應用
guider top -q ANDAPP

# 顯示系統百分比
guider top -q SYSPER

# KB 為單位顯示
guider top -q KBUNIT

# 顯示 Cgroup 信息
guider top -q PRINTCG

# 顯示 Cgroup 信息（指定類型）
guider top -q PRINTCG:"cpu+cpuacct+memory+blkio"

# 快速初始化
guider top -q FASTINIT

# 不轉換大小單位
guider top -q NOCONVSIZE

# 不轉換時間單位
guider top -q NOCONVTIME

# 不格式化數字
guider top -q NOCONVNUM

記錄與重播

# 記錄 3 秒並輸出到文件
# 注意：輸出文件名會自動添加時長後綴
guider top -R 1:3:auto -o /tmp/test.out
# 實際輸出文件：/tmp/test.out_00:00:03

# 記錄 10 秒
guider top -R 1:10:auto -o /tmp/guider.out
# 實際輸出文件：/tmp/guider.out_00:00:10

# 生成視覺化圖表（注意使用完整文件名）
guider draw /tmp/test.out_00:00:03
# 輸出：/tmp/test_graph.svg

# 生成 CPU 圖表
guider drawcpu /tmp/test.out_00:00:03
# 輸出：/tmp/test_graph.svg

# 生成記憶體圖表
guider drawmem /tmp/test.out_00:00:03
# 輸出：/tmp/test_graph.svg

過濾選項

# 監控特定 PID
guider top -g 1234

# 監控特定進程名
guider top -g chrome

# 使用萬用字元
guider top -g "chrome*"
guider top -g "*worker"

# 排除特定進程
guider top -g "^test"

# 用戶過濾
guider top -q USERFILTER:"root*"

條件控制

# 等待用戶輸入後開始
guider top -a -W

# 等待 5 秒後開始
guider top -a -W 5s

# 從系統啟動 100 秒後開始
guider top -a -q STARTCONDTIME:100

# 當特定任務創建時開始
guider top -a -q STARTCONDTASK:"yes|test*"

# 當文件存在時開始
guider top -a -q STARTCONDFILE:"/tmp/start"

# 當文件不存在時開始
guider top -a -q STARTCONDNOFILE:"/tmp/stop"

# CPU 使用率大於 10% 時開始
guider top -a -q STARTCONDCPUMORE:10 -R

# 特定進程結束時退出
guider top -a -q EXITCONDTERM:"a.out"

# 新進程啟動時退出
guider top -a -q EXITCONDNEW:"test"

# 運行到指定時間退出
guider top -a -q EXITCONDTIME:100

JSON 輸出

# JSON 格式輸出
guider top -J

# 完整 JSON 統計
guider top -J -q ALLJSONSTAT

# 過濾 JSON 欄位
guider top -J -q JSONFILTER:"*mem", JSONFILTER:"*cpu"

實用範例

系統監控範例

# 1. 監控所有進程，顯示完整統計
guider top -a

# 2. 監控 CPU 使用率超過 1% 的進程
guider top -S c:1

# 3. 監控記憶體使用超過 500MB 的進程
guider top -S m:500

# 4. 監控特定進程並記錄 30 秒
guider top -g chrome -R 1:30:auto -o /tmp/chrome.out
# 實際輸出文件：/tmp/chrome.out_00:00:30

# 5. 顯示進程樹狀結構
guider pstree

# 6. 顯示進程列表
guider ps

# 7. 監控文件 I/O 操作（需要 root）
sudo guider ftop -a

# 8. 監控網路連接
guider ntop -a

# 9. 監控系統調用（需要 root）
sudo guider systop -a

# 10. 顯示進程的命令行參數
guider top -e L

# 11. 顯示線程級別的詳細信息
guider ttop -a

# 12. 按執行時間排序進程
guider top -S e

# 13. 顯示進程的 CPU 親和性
guider top -e a

# 14. 顯示記憶體詳細信息（包含 PSS）
guider top -e S

# 15. 監控阻塞的進程
guider top -e b -S b:100

效能分析範例

# 1. 記錄系統效能 60 秒（需要 root）
sudo guider rec -R 1:60:auto -o /tmp/rec.out
# 實際輸出文件：/tmp/rec.out_00:01:00

# 2. 使用 top 記錄（不需要 root）
guider top -a -R 1:60:auto -o /tmp/top.out
# 實際輸出文件：/tmp/top.out_00:01:00

# 3. 生成視覺化圖表
guider draw /tmp/top.out_00:01:00
# 輸出：/tmp/top_graph.svg

# 4. 生成 CPU 使用圖表
guider drawcpu /tmp/top.out_00:01:00
# 輸出：/tmp/top_graph.svg

# 5. 生成記憶體使用圖表
guider drawmem /tmp/top.out_00:01:00
# 輸出：/tmp/top_graph.svg

# 6. 生成火焰圖（需要函數追蹤數據）
sudo guider funcrec -R 1:10:auto -o /tmp/func.out
guider drawflame /tmp/func.out_00:00:10

故障診斷範例

# 1. 追蹤記憶體洩漏
guider leaktrace <PID>

# 2. 追蹤系統調用
guider strace <PID>

# 3. 追蹤信號
guider sigtrace <PID>

# 4. 轉儲進程堆疊
guider dumpstack <PID>

# 5. 查看進程的 CPU 親和性
guider getafnt <PID>

# 6. 查看系統信息
guider printinfo

# 7. 查看內核配置
guider printkconf

# 8. 查看 Slab 記憶體
guider printslab

壓力測試範例

# 1. CPU 壓力測試（4 線程）
guider cputest 4

# 2. 記憶體壓力測試（1GB）
guider memtest 1024

# 3. I/O 壓力測試（100MB）
guider iotest 100

# 4. 網路測試
guider nettest 127.0.0.1

進階用法範例

# 1. 監控並在 CPU 超過 80% 時自動記錄
guider top -a -q STARTCONDCPUMORE:80 -R 60 -o

# 2. 監控特定目錄的文件變化
guider top -a -q MONDIR:"/tmp/test"

# 3. 監控並顯示 GPU 記憶體
guider top -a -q GPUMEM

# 4. 監控並顯示 GPU 溫度
guider top -a -q GPUTEMP

# 5. 監控容器資源使用
guider contop -a

# 6. 監控 D-Bus 活動
guider dbustop -a

# 7. 以條形圖顯示 CPU 使用
guider top -a -e B

# 8. 監控並在程序結束時執行命令
guider top -a -q EXITCMD:"ls -lha"

# 9. 結合多個條件
guider top -a -q STARTCONDCPUMORE:10, STARTCONDMEMMORE:1000 -R

# 10. 流式輸出（適合管道處理）
guider top -a -q TASKSTREAM -Q -S c:1

視覺化範例

# 1. 記錄數據（實際文件名會包含時長）
guider top -R 1:60:auto -o /tmp/data.out
# 實際輸出文件：/tmp/data.out_00:01:00

# 2. 生成系統總覽圖表
guider draw /tmp/data.out_00:01:00
# 輸出：/tmp/data_graph.svg

# 3. 生成 CPU 使用趨勢圖
guider drawcpu /tmp/data.out_00:01:00
# 輸出：/tmp/data_graph.svg（會覆蓋之前的圖表）

# 4. 生成記憶體使用趨勢圖
guider drawmem /tmp/data.out_00:01:00
# 輸出：/tmp/data_graph.svg（會覆蓋之前的圖表）

# 5. 生成火焰圖（需要函數追蹤數據）
sudo guider funcrec -R 1:10:auto -o /tmp/func.out
guider drawflame /tmp/func.out_00:00:10

# 6. 生成直方圖
guider drawhist /tmp/data.out_00:01:00

# 7. 生成小提琴圖
guider drawviolin /tmp/data.out_00:01:00

# 8. 比較兩個數據文件
guider drawdiff /tmp/data1.out_00:01:00 /tmp/data2.out_00:01:00

# 9. 生成平均值圖表
guider drawavg /tmp/data.out_00:01:00

# 10. 生成時間軸圖表
guider drawtime /tmp/data.out_00:01:00

注意事項

1. 權限要求：某些指令需要 root 權限才能完全運行，例如 ftop、strace、rec、funcrec 等。
2. 輸出文件命名：
   • 使用 -o 參數記錄時，實際輸出文件名會自動添加時長後綴
   • 例如：-o /tmp/test.out 實際輸出為 /tmp/test.out_00:00:03
   • 視覺化時需要使用完整的文件名（包含時長後綴）
3. 視覺化輸出：
   • 默認輸出為 SVG 格式，文件名為 <basename>_graph.svg
   • 多次運行會自動備份舊文件為 _old.svg
4. 平臺相容性：不同平臺支援的指令不同，請參考指令分類中的平臺支援欄位。
5. 資源消耗：持續監控會消耗系統資源，建議根據需要調整監控間隔和範圍。
6. 視覺化要求：視覺化功能需要安裝 matplotlib 和 numpy：

   pip install -r guider/requirements.txt
   

進階參數詳解

時間與間隔控制

# -i: 設定間隔（秒）
guider top -i 2           # 每 2 秒更新
guider top -i 0.5         # 每 0.5 秒更新

# -R: 設定重複計數 (INTERVAL:TIME:TERM)
guider top -R 1:10:auto   # 每 1 秒，總共 10 秒，自動結束
guider top -R 2:60:manual # 每 2 秒，總共 60 秒，手動結束

# -W: 等待輸入或時間
guider top -W             # 等待用戶按鍵開始
guider top -W 5           # 等待 5 秒開始
guider top -W 5s          # 等待 5 秒開始（明確單位）

輸出與日誌控制

# -o: 設定輸出路徑（檔案會自動添加時長後綴）
guider top -o /tmp/test.out        # 輸出到 /tmp/test.out_HH:MM:SS
guider top -o .                    # 輸出到當前目錄
guider top -o /var/log/guider/     # 輸出到指定目錄

# -L: 設定日誌文件
guider top -L /tmp/guider.log      # 記錄日誌到指定文件

# -l: 設定日誌類型
guider top -l a                    # Android 日誌
guider top -l d                    # DLT 日誌
guider top -l k                    # KMSG 日誌
guider top -l j                    # Journal 日誌
guider top -l s                    # Syslog 日誌

效能與資源控制

# -b: 設定緩衝區大小
guider top -b 1024                 # 1024 KB 緩衝區
guider top -b 50m                  # 50 MB 緩衝區
guider top -b 1g                   # 1 GB 緩衝區

# -T: 設定進程數量限制
guider top -T 100                  # 最多顯示 100 個進程
guider top -T 50                   # 最多顯示 50 個進程

網路與遠端控制

# -x: 設定本地地址
guider top -x 127.0.0.1:5555       # 綁定本地地址和端口

# -X: 設定請求地址
guider top -X req@192.168.1.100:5555

# -N: 設定報告地址
guider top -N report@192.168.1.100:5555

常見問題

Q1: 如何在背景執行監控？

guider top -u -R 1:3600:auto -o /tmp/monitor.out
# 實際輸出文件：/tmp/monitor.out_01:00:00

Q2: 如何監控特定用戶的所有進程？

guider top -q USERFILTER:"username*"

Q3: 如何生成定期報告？

# 使用 cron 定期執行
0 * * * * guider top -R 1:300:auto -o /var/log/guider/hourly.out
# 實際輸出文件：/var/log/guider/hourly.out_00:05:00

Q4: 如何監控 Docker 容器？

guider contop -a

Q5: 如何追蹤特定函數的調用？

# 需要 root 權限
sudo guider btrace <function_name>

Q6: 如何查看所有可用的環境變量選項？

# 使用 --help 查看完整列表
guider top --help | grep -A 100 "set environment"

Q7: 如何同時監控多個條件？

# CPU 和記憶體同時超過閾值
guider top -a -q STARTCONDCPUMORE:80, STARTCONDMEMMORE:1000 -R

# 多個過濾條件
guider top -g "chrome*" -S c:5 -q USERFILTER:"user*"

Q8: 如何自定義輸出格式？

# JSON 格式
guider top -J

# 流式輸出
guider top -Q

# 不轉換單位
guider top -q NOCONVSIZE, NOCONVTIME, NOCONVNUM

完整參數快速參考

監控類命令通用參數

啟用選項 (-e) 詳細說明

更多資源

• 官方文檔：查看項目 README.md
• 配置文件：編輯 guider.conf 進行自定義配置
• 問題回報：https://github.com/iipeace/guider/issues
• 源碼倉庫：https://github.com/iipeace/guider

本指南基於 Guider 3.9.9_250918 版本編寫，測試於 Ubuntu Linux 6.14.0，不同版本和平臺可能有所差異。