facebookresearch/HolisticTraceAnalysis

Holistic Trace Analysis (HTA)

무엇인가요 – HTA는 분산형 PyTorch 학습 작업이 느린 이유를 이해하는 데 도움을 주는 Python 라이브러리입니다. PyTorch 프로파일러(Kineto)가 생성한 트레이스 파일을 읽어 GPU가 계산, 통신, 메모리 작업, 또는 대기 상태에 얼마나 시간을 쓰는지 정확히 파악할 수 있는 데이터프레임과 시각화를 제공합니다.

주요 기능

기능	제공되는 내용
시간 분해	GPU별 시간을 계산, 통신, 메모리 작업, 대기 시간으로 분할
커널 분해 및 분포	각 랭크별로 가장 오래 실행된 CUDA 커널 목록과 랭크 간 실행 시간의 차이를 시각화
대기 시간 분석	GPU가 대기 상태인 이유(호스트 대기, 다른 커널 대기, 알 수 없음)를 분석
통신-계산 겹침	통신이 유용한 계산과 겹치는 시간 비율
자주 발생하는 커널 패턴	특정 PyTorch 연산자(예: aten::linear)에 대해 가장 자주 반복되는 CUDA 커널 탐지
커널 실행 통계	매우 짧거나 매우 긴, 또는 비정상적으로 지연된 커널 실행 시간의 히스토그램
증강된 카운터	원본 프로파일에 큐 길이 및 메모리 대역폭 트레이스를 추가하여 루프라인 분석 가능
트레이스 비교	두 실행 결과를 비교하여 변화를 확인
CUPTI 카운터 API(실험적)	GPU 성능 카운터를 낮은 수준에서 추출하여 심층적인 루프라인 분석 가능

대상 사용자 – 여러 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 프로파일러 사용 (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 프로파일러 트레이스를 실행 가능한 성능 보고서로 변환하여, 분산 학습 파이프라인 최적화를 더 쉽게 만듭니다.