facebookresearch/HolisticTraceAnalysis

全面追蹤分析 (HTA)

是什麼 – HTA 是一個 Python 庫，協助研究人員與工程師理解分散式 PyTorch 訓練作業為何變慢。它讀取 PyTorch Profiler（Kineto）產生的追蹤檔，並轉換為一組即用型的資料框與視覺化圖表，精準指出 GPU 在計算、通訊、記憶體操作或閒置狀態上耗費的時間。

核心功能

功能	你將獲得
時間分解	按 GPU 分解時間，分為計算、通訊、記憶體操作與閒置時段。
內核分解與分布	列出每個 rank 上執行時間最長的 CUDA 內核，並展示其在不同 rank 間的持續時間差異。
閒置時間分析	顯示 GPU 處於閒置狀態的原因（等待主機、等待其他內核、未知）。
通訊-計算重疊	通訊與有用計算重疊的時間比例。
頻繁內核模式	為特定 PyTorch 操作符（如 aten::linear）找出最常重複出現的 CUDA 內核。
內核啟動統計	非常短、非常長、或異常延遲的內核啟動時間的直方圖。
增強計數器	在原始性能分析中新增佇列長度與記憶體頻寬追蹤，用於類似 Roofline 的分析。
追蹤對比	兩個執行結果的並排差異分析，查看變動。
CUPTI 計數器 API（實驗性）	提取低階 GPU 性能計數器，支援更深入的 Roofline 分析。

適用對象 – 任何在多個 GPU/主機上訓練大型模型，希望以系統化、可腳本化方式定位瓶頸，而無需手動挖掘原始性能分析輸出的人。

安裝

# 從 PyPI（推薦）
pip install HolisticTraceAnalysis

# 或從原始碼安裝
git clone https://github.com/facebookresearch/HolisticTraceAnalysis.git
cd HolisticTraceAnalysis
git submodule update --init
pip install -r requirements.txt
pip install -e .

支援 Linux 與 macOS，需 Python ≥ 3.10。

典型工作流程

1. 收集追蹤資料 使用 PyTorch Profiler（torch.profiler.profile(..., record_shapes=True, with_stack=True, ...)）。
2. 將所有追蹤檔案放入一個資料夾 – HTA 期望每個執行對應一個獨立目錄。
3. 開啟一個筆記本（或 Python 腳本）並建立 TraceAnalysis 物件：

   from hta.trace_analysis import TraceAnalysis
   analyzer = TraceAnalysis(trace_dir="/path/to/traces")
   

4. 呼叫所需方法，例如：

   temporal = analyzer.get_temporal_breakdown()
   kernels  = analyzer.get_gpu_kernel_breakdown()
   idle     = analyzer.get_idle_time_breakdown()
   overlap  = analyzer.get_comm_comp_overlap()
   

   每個方法回傳一個 pandas DataFrame，可用於繪圖或檢查。
5. 深入分析時，可使用 examples/ 中的示範筆記本（trace_analysis_demo.ipynb, trace_diff_demo.ipynb）。

設定 – 日誌控制透過 hta/configs/logging.config 進行；可變更日誌等級或指定自訂設定檔。

文件與支援 – 完整 API 文件托管於 https://hta.readthedocs.io。專案採用 MIT 許可證開源，歡迎透過拉取請求貢獻程式碼。

---

總結 – HTA 將原始 PyTorch Profiler 追蹤資料轉化為可操作的性能報告，使優化分散式訓練流程變得更加容易。